Vistas y procedimientos almacenados personalizados

La A3ERP API permite extender su funcionalidad con dos mecanismos de personalización: vistas SQL registradas en el diccionario JNCAPI y procedimientos almacenados de SQL Server definidos en cualquier otro diccionario. Ambos te permiten acceder a datos o lógicas específicas de tu empresa sin modificar el núcleo de la API.

1. Vistas personalizadas

Las vistas personalizadas son consultas SQL que defines y registras en el diccionario JNCAPI mediante la herramienta CfgVistas.exe. Una vez registradas, puedes ejecutarlas a través de la API como si fueran un endpoint más.

Crear y gestionar vistas

Abre CfgVistas.exe desde la carpeta de instalación de la API.
Verás la lista de vistas ya configuradas por defecto.
Para crear una nueva vista, pulsa el botón Nueva — se añadirá al final con orden -1.
Define la consulta SQL de la vista y guarda los cambios.

Las vistas se almacenan en la base de datos y se cargan en memoria al iniciar el servicio. Después de crear o modificar una vista, debes reiniciar el servicio A3ERP API para que los cambios estén disponibles.

Solo se pueden ejecutar vistas que estén registradas en el diccionario JNCAPI. Si intentas llamar a una vista que no existe en el diccionario, la API devolverá un error.

Ejecutar una vista

Llama al endpoint GET /api/vista/{nombre_vista} con tu token JWT en la cabecera Authorization:

GET /api/vista/{nombre_vista} HTTP/1.1
Host: <domain>:<port>
Authorization: Bearer {JWT Token}
Accept: */*

Ejemplo — ejecutar la vista Api_Vinculos:

curl -X GET https://miservidor:5555/api/vista/Api_Vinculos \
  -H "Authorization: Bearer {JWT Token}"

Las vistas admiten filtrado y ordenación igual que el resto de endpoints. Por ejemplo:

# Filtrar por cliente
curl -X GET "https://miservidor:5555/api/vista/Api_Vinculos/filtro/codcli='000001'" \
  -H "Authorization: Bearer {JWT Token}"

# Ordenar por fecha descendente
curl -X GET "https://miservidor:5555/api/vista/Api_Vinculos/order/fecha desc" \
  -H "Authorization: Bearer {JWT Token}"

Generar informes desde una vista

Si la vista tiene asociado un formato FastReport, puedes generar el informe en PDF o Excel:

GET /api/vista/{nombre_vista}/impresion/pdf

Los archivos generados se suben al servidor FTP configurado en el Config.ini y están disponibles para su descarga.

2. Procedimientos almacenados

Los procedimientos almacenados te permiten ejecutar lógica SQL personalizada en el servidor de base de datos directamente desde la API. A diferencia de las vistas, los procedimientos se ejecutan sin restricciones sobre el código que contienen.

Solo se pueden ejecutar procedimientos almacenados que estén definidos en diccionarios distintos al JNCAPI. Los procedimientos del diccionario JNCAPI están reservados para uso interno de la API.

Ejecutar un procedimiento almacenado

Usa POST /api/procalm/{procedimiento} enviando los parámetros en el cuerpo de la petición como JSON:

POST /api/procalm/{procedimiento} HTTP/1.1
Host: <domain>:<port>
Authorization: Bearer {JWT Token}
Content-Type: application/json
Accept: */*

Cuerpo de la petición:

{
  "parametros": [
    {
      "nombre": "nombre_del_parametro",
      "tipo": "string",
      "direccion": "entrada",
      "longitud": "8",
      "defecto": "",
      "valor": "valorejemplo"
    }
  ]
}

Campos de cada parámetro

Campo	Descripción
`nombre`	Nombre del parámetro tal como está definido en el procedimiento SQL.
`tipo`	Tipo de dato del parámetro (ver tabla de tipos más abajo).
`direccion`	Dirección del parámetro: si es de entrada, salida o ambas (ver tabla de direcciones).
`longitud`	Longitud del parámetro en caracteres. Usa `"0"` para tipos numéricos.
`defecto`	Valor por defecto si no se proporciona un valor.
`valor`	Valor concreto que se pasa al procedimiento.

Tipos de datos válidos

Tipo	Descripción
`string`	Cadena de texto.
`integer`	Número entero.
`boolean`	Valor booleano (verdadero/falso).
`float`	Número decimal de punto flotante.
`currency`	Valor monetario.
`word`	Entero sin signo de 16 bits.
`date`	Fecha.
`time`	Hora.
`text`	Texto largo.
`binary`	Datos binarios.

Direcciones válidas

Dirección	Descripción
`entrada`	El parámetro solo se envía al procedimiento.
`salida`	El procedimiento devuelve un valor en este parámetro.
`entradasalida`	El parámetro se envía y el procedimiento puede modificarlo y devolverlo.
`retorno`	Valor de retorno del procedimiento.

Ejemplo completo

Llamada al procedimiento procedimientodeprueba con un parámetro de entrada (codigo) y uno de salida (riesgo): URL:

https://miservidor:5555/api/procalm/procedimientodeprueba

Petición curl:

curl -X POST https://miservidor:5555/api/procalm/procedimientodeprueba \
  -H "Authorization: Bearer {JWT Token}" \
  -H "Content-Type: application/json" \
  -d '{
    "parametros": [
      {
        "nombre": "codigo",
        "tipo": "string",
        "direccion": "entrada",
        "longitud": "8",
        "defecto": "",
        "valor": " 1"
      },
      {
        "nombre": "riesgo",
        "tipo": "float",
        "direccion": "salida",
        "longitud": "0",
        "defecto": "0",
        "valor": "0"
      }
    ]
  }'

La respuesta incluirá los valores de los parámetros de salida junto con cualquier conjunto de resultados que devuelva el procedimiento.

Inicio Rápido

Conceptos Clave

Versiones

Vistas y procedimientos almacenados personalizados

1. Vistas personalizadas

Crear y gestionar vistas

Ejecutar una vista

Generar informes desde una vista

2. Procedimientos almacenados

Ejecutar un procedimiento almacenado

Campos de cada parámetro

Tipos de datos válidos

Direcciones válidas

Ejemplo completo

​1. Vistas personalizadas

​Crear y gestionar vistas

​Ejecutar una vista

​Generar informes desde una vista

​2. Procedimientos almacenados

​Ejecutar un procedimiento almacenado

​Campos de cada parámetro

​Tipos de datos válidos

​Direcciones válidas

​Ejemplo completo

1. Vistas personalizadas

Crear y gestionar vistas

Ejecutar una vista

Generar informes desde una vista

2. Procedimientos almacenados

Ejecutar un procedimiento almacenado

Campos de cada parámetro

Tipos de datos válidos

Direcciones válidas

Ejemplo completo