API de Acqua ERP
El servidor expone seis endpoints de integración, agrupados en tres familias. Esta página es para elegir cuál te sirve; el detalle de cada uno está en los otros dos documentos.
Mapa de canales
OData v4
Acceso REST estándar a los maestros del ERP. Es autodescriptivo: el cliente descubre solo qué entidades hay, qué campos tienen y cómo se relacionan. Es el único canal que entienden Power BI y Excel sin programar nada.
GET POST PUT PATCH DELETE
/jwt-odata/* — con JWT
/jwt-odata-key/* — con API key
Query
Ejecuta una consulta SQL predefinida por el administrador y devuelve el resultado como array JSON. No se manda SQL: se manda el identificador de la consulta y sus parámetros. Sirve para reportes puntuales sin publicar la entidad entera.
GET POST
/jwt — con JWT
/jwt-key — con API key
Transacciones
Ejecuta las transacciones del ERP: un CRUD sobre una transacción existente, o una transacción propia con su estructura. A diferencia de OData, acá corren las pantallas del ERP tal como las usa un operador, con sus reglas y procesos.
POST
/jwt-api — con usuario y contraseña
/jwt-key-api — con API key
¿Cuál uso?
| Lo que necesito | Canal | Por qué |
|---|---|---|
| Un informe en Power BI o Excel que se actualice solo | /jwt-odata-key/* | Las dos herramientas traen conector OData. Con API key no hay token que renovar, así que el refresco programado no se cae. |
| Leer maestros desde mi aplicación, con filtros y paginación | /jwt-odata/* | $filter, $select, $orderby y $expand sin escribir SQL ni publicar nada nuevo. |
| Crear o modificar registros de un maestro | /jwt-odata/* | Una escritura OData abre la transacción real del ERP, con sus reglas y validaciones. |
| Un reporte con lógica propia (joins, agregaciones, varias tablas) | /jwt-key | OData no hace agregaciones. Acá el administrador deja la consulta armada y vos la invocás por su nombre. |
| Disparar un proceso del ERP que no es un alta de maestro | /jwt-key-api | Ejecuta la transacción completa, incluidos sus procesos y scripts. |
| Operar en nombre de un usuario que se autentica con su contraseña | /jwt-api | Es el único canal donde la credencial es el usuario final del ERP y no una clave de integración. |
Autenticación de un vistazo
Dos métodos. El que corresponde no se elige: lo define el endpoint.
| JWT Bearer | API Key | |
|---|---|---|
| Header | Authorization: Bearer <token> | X-API-Key: <clave> |
| Paso previo | Sí, pedir el token | No |
| Vigencia | 12 horas, sin refresco: se vuelve a pedir | No caduca; se puede desactivar |
| Se valida | Al pedir el token y en cada pedido (firma y vencimiento) | En cada pedido, contra la clave y su estado |
| Lista blanca de IP | Sí, salvo en /jwt-api | Sí, en los tres endpoints |
| Endpoints | /jwt /jwt-api /jwt-odata/* | /jwt-key /jwt-key-api /jwt-odata-key/* |
Elegí API key para todo lo automático. El token vive 12 horas y no hay refresh: cualquier proceso desatendido que dure más que eso se va a cortar. Con API key no hay nada que renovar.
/jwt-api es la excepción en todo. Es el único canal que se autentica con el usuario y la contraseña de una persona del ERP en lugar de una clave de integración, y el único que no valida la IP de origen. Si estás integrando un sistema, casi siempre querés otro.
URL base y formato
Todas las rutas de estos documentos se cuelgan de la raíz de la aplicación:
https://TU-HOST/synergy-server/
Las respuestas son JSON en UTF-8, con tres excepciones, todas en OData: $metadata devuelve XML, $count y $value de texto devuelven text/plain, y $value de un campo binario devuelve application/octet-stream.
Clientes de ejemplo
Listos para descargar y usar:
- synergy-odata.postman_collection.json — Colección de Postman con 28 pedidos: descubrimiento, lectura, filtros, maestros relacionados, escritura y el login JWT. Es la forma más rápida de probar sin escribir código.
- ejemplo_odata.py — Python con
requests: lee el modelo, cuenta, y recorre todas las páginas siguiendo@odata.nextLink. - power-query-odata.pq — Cinco fragmentos de Power Query (M) para Excel y Power BI, con API key y con JWT.
Documentación de la API de Acqua ERP — generada desde el código del servidor. Si algo no coincide con lo que responde tu instalación, el código manda: avisanos.