Canales de API de Acqua ERP

Los endpoints de integración que no son OData: ejecutar consultas que el administrador dejó preparadas y disparar transacciones del ERP. Para leer y escribir maestros con un cliente estándar, usá OData.

nota

Cómo usar esta página. Los ejemplos usan https://TU-HOST/synergy-server/ como raíz: reemplazá TU-HOST por el servidor que te pasaron. Todos los bloques de código tienen botón de copiar.

Arranque rápido

La forma más corta de obtener datos: una consulta predefinida con API key, en un solo pedido.

curl -s -H "X-API-Key: TU_API_KEY" \
  "https://TU-HOST/synergy-server/jwt-key?id_query=clientes_activos"

# respuesta: un array plano, una entrada por fila
[
  { "id": 1, "nombre": "Empresa A" },
  { "id": 2, "nombre": "Empresa B" }
]

El id_query no es SQL: es el nombre de una consulta que el administrador cargó y asignó a tu cliente. Si no sabés qué consultas tenés disponibles, no hay forma de listarlas desde la API — hay que preguntarle a quien administra el servidor.

1. Autenticación

Cada endpoint acepta un solo método. No se elige.

Endpoint	Credencial	Para qué
`/jwt-key`	`X-API-Key`	Consultas predefinidas
`/jwt-key-api`	`X-API-Key`	Transacciones
`/jwt`	token de `id_client`	Consultas predefinidas
`/jwt-api`	token de usuario y contraseña	Transacciones

Con API key

Un header en cada pedido, sin paso previo. No caduca.

X-API-Key: TU_API_KEY

En cada pedido se verifican tres cosas: que la clave exista, que esté activa, y que tu IP de salida esté autorizada. Si falla cualquiera de las tres, la respuesta es 403 y no dice cuál: es a propósito. Si la clave es correcta y recibís 403, lo más probable es la IP — la del proxy o el NAT si salís por uno.

Con JWT

Dos pasos: pedir el token y después usarlo en el header Authorization. El token vale 12 horas y no hay refresco: cuando vence se vuelve a pedir desde cero.

aviso

Para procesos desatendidos, usá API key. Las 12 horas no son configurables, así que cualquier integración que corra sola más tiempo que eso se va a cortar a mitad de camino.

2. Query con JWT — `/jwt`

Ejecuta una consulta predefinida y devuelve las filas como array JSON. El cliente de integración se identifica con id_client, sin contraseña.

Paso 1: pedir el token

GET https://TU-HOST/synergy-server/jwt?type=token&id_client=<ID>

curl -s "https://TU-HOST/synergy-server/jwt?type=token&id_client=MI_CLIENTE"

{ "token": "eyJhbGciOiJIUzI1NiJ9.eyJ0cyI6IjE3MDAwMDAwMDAwMDAifQ..." }

Se valida que el id_client esté registrado y que tu IP esté autorizada.

Paso 2: ejecutar la consulta

GET https://TU-HOST/synergy-server/jwt?type=query&id_client=<ID>&id_query=<CONSULTA>

Parámetro		Qué es
`type`	❌ obligatorio	`token` o `query`
`id_client`	❌ obligatorio	Tu cliente de integración
`id_query`	❌ obligatorio	Nombre de la consulta
`param`	⚠️ opcional	Parámetros de la consulta. Se repite una vez por cada uno, y se asignan en orden a los `?` de la consulta.

curl -s -H "Authorization: Bearer $TOKEN" \
  --get "https://TU-HOST/synergy-server/jwt" \
  --data-urlencode "type=query" \
  --data-urlencode "id_client=MI_CLIENTE" \
  --data-urlencode "id_query=ventas_por_zona" \
  --data-urlencode "param=Buenos Aires" \
  --data-urlencode "param=2026"

Los param van siempre como valores, nunca concatenados en el SQL, así que no hay riesgo de inyección por ese lado.

Respuestas

Status	Cuerpo	Cuándo
`200`	Array JSON	La consulta corrió. Si no hay filas, el array viene vacío.
`204`	sin cuerpo	La consulta no existe o no está asignada a tu cliente. Ver §7.
`403`	sin cuerpo	Token inválido, token vencido, o IP no autorizada.
`500`	sin cuerpo	Error del servidor — o un parámetro obligatorio que falta. Ver §7.

nota

POST hace lo mismo que GET. El endpoint acepta los dos y el POST se procesa igual, leyendo los parámetros del formulario. Útil si la consulta lleva parámetros largos que no querés en la URL.

3. Query con API key — `/jwt-key`

Lo mismo que §2 en un solo pedido. El id_client no se manda: sale de la propia clave.

GET https://TU-HOST/synergy-server/jwt-key?id_query=<CONSULTA>

curl -s -H "X-API-Key: TU_API_KEY" \
  --get "https://TU-HOST/synergy-server/jwt-key" \
  --data-urlencode "id_query=ventas_por_zona" \
  --data-urlencode "param=Buenos Aires"

Las respuestas son las de §2, más una: si falta id_query, la respuesta es 400. Y POST también se acepta.

4. Transacciones con JWT — `/jwt-api`

Ejecuta las transacciones del ERP. Es el único canal cuya credencial es un usuario real con su contraseña, y el único que no valida la IP de origen.

Solo acepta POST . Un GET devuelve 405.

Paso 1: pedir el token

POST https://TU-HOST/synergy-server/jwt-api?type=token

curl -s -X POST "https://TU-HOST/synergy-server/jwt-api?type=token" \
  -H "Content-Type: application/json" \
  -d '{"user":"integrador","password":"..."}'

{
  "token": "eyJhbGciOiJIUzI1NiJ9...",
  "type": "Bearer",
  "expires_in": 43200,
  "created_at": 1700000000
}

expires_in está en segundos (43200 = 12 horas) y created_at es un timestamp Unix en segundos. Si el login falla, la respuesta es 403 sin cuerpo.

Paso 2a: CRUD sobre una transacción

POST https://TU-HOST/synergy-server/jwt-api?type=crud

curl -s -X POST "https://TU-HOST/synergy-server/jwt-api?type=crud" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id_transaction": "o_customers",
    "operation": "create",
    "fields": [
      {"name": "nombre", "value": "Nuevo Cliente"},
      {"name": "email",  "value": "nuevo@ejemplo.com"}
    ]
  }'

Campo	Qué es
`id_transaction`	La transacción del ERP a ejecutar.
`operation`	`create`, `read`, `update` o `delete`.
`fields`	Array de `{name, value}`. Para `update` y `delete` hay que incluir los campos de la clave.

aviso

El resultado viene en el cuerpo, no solo en el status. La respuesta trae un campo result; cuando vale "error" el status es 400. O sea que un 200 no alcanza: hay que mirar result igual.

Paso 2b: transacción propia

POST https://TU-HOST/synergy-server/jwt-api?type=transaction

El cuerpo es el JSON de la transacción tal como está definida en el servidor. La estructura depende de cada transacción; la tiene quien la programó.

5. Transacciones con API key — `/jwt-key-api`

Idéntico a §4 pero sin paso previo, y sí valida la IP. El cuerpo de type=crud y type=transaction es el mismo.

curl -s -X POST "https://TU-HOST/synergy-server/jwt-key-api?type=crud" \
  -H "X-API-Key: TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id_transaction": "o_customers",
    "operation": "update",
    "fields": [
      {"name": "id",     "value": "123"},
      {"name": "nombre", "value": "Cliente Actualizado"}
    ]
  }'

Los únicos type válidos son crud y transaction; cualquier otro devuelve 400. Solo acepta POST .

nota

La transacción corre como un usuario del ERP. Cuál, lo decide el administrador al dar de alta la clave. Si ese usuario no tiene permiso sobre la pantalla, la escritura falla aunque la clave sea válida — y el mensaje de error habla de seguridad, no de la API.

6. Códigos de estado

Status	Cuándo
`200`	El pedido se procesó. En `type=crud` hay que mirar igual el campo `result` del cuerpo.
`204`	Una consulta que no existe o no está asignada a tu cliente.
`400`	Falta `id_query`, el `type` no es válido, o la transacción devolvió un error de negocio.
`401`	No mandaste el header `X-API-Key`.
`403`	Clave inválida o inactiva, IP no autorizada, token inválido o vencido, login fallido.
`405`	Método HTTP que el endpoint no acepta — por ejemplo `GET` en `/jwt-api`.
`500`	Error del servidor. En estos canales también aparece cuando falta un parámetro obligatorio: ver §7.

Los endpoints de OData no usan esta tabla: devuelven el formato de error del protocolo, con su propio catálogo de códigos. Está en la guía de OData.

7. Errores que confunden

Estos canales son los más viejos del servidor y en algunos casos responden de una forma que no se corresponde con el problema. Vale conocerlos antes de perder una tarde.

204 No Content cuando esperabas 403 — En /jwt y /jwt-key, una consulta que no existe y una consulta que existe pero no está asignada a tu cliente devuelven lo mismo: un 204 sin cuerpo. No es que no haya filas — cuando la consulta corre y no devuelve nada, el status es 200 con un array vacío. Un 204 es siempre un problema de configuración; pedile al administrador que verifique que la consulta esté asignada.
500 cuando falta un parámetro — En /jwt, omitir type o llamar a type=query sin el header Authorization termina en 500, no en 400. Si te da 500 en el primer intento de integración, revisá los parámetros antes de sospechar del servidor.
200 con cuerpo vacío al pedir un token — En /jwt?type=token, un id_client que no está registrado devuelve 200 sin cuerpo en lugar de un error. Si esperabas {"token": "..."} y recibiste nada, el id_client está mal escrito o no fue dado de alta.
403 sin explicación — Con API key, las tres causas — clave inexistente, clave inactiva, IP no autorizada — dan el mismo 403 sin cuerpo, a propósito, para no filtrarle información a quien prueba claves. Si la clave la acabás de recibir y funciona desde otra red, es la IP.
La escritura falla pero la credencial es correcta — En /jwt-key-api y /jwt-api, las transacciones corren como un usuario del ERP y respetan sus permisos. Un error de seguridad al guardar significa que a ese usuario le falta permiso sobre la pantalla, no que la API esté mal. El administrador lo resuelve del lado del ERP.

Canales de API de Acqua ERP — para leer y escribir maestros con un cliente estándar, ver la guía de OData.

Arranque rápido​

1. Autenticación​

Con API key​

Con JWT​

2. Query con JWT — /jwt​

Paso 1: pedir el token​

Paso 2: ejecutar la consulta​

Respuestas​

3. Query con API key — /jwt-key​

4. Transacciones con JWT — /jwt-api​

Paso 1: pedir el token​

Paso 2a: CRUD sobre una transacción​

Paso 2b: transacción propia​

5. Transacciones con API key — /jwt-key-api​

6. Códigos de estado​

7. Errores que confunden​

Arranque rápido

1. Autenticación

Con API key

Con JWT

2. Query con JWT — `/jwt`

Paso 1: pedir el token

Paso 2: ejecutar la consulta

Respuestas

3. Query con API key — `/jwt-key`

4. Transacciones con JWT — `/jwt-api`

Paso 1: pedir el token

Paso 2a: CRUD sobre una transacción

Paso 2b: transacción propia

5. Transacciones con API key — `/jwt-key-api`

6. Códigos de estado

7. Errores que confunden