API

Guía de la API REST de WAMA

Integra tus sistemas con WAMA mediante la API JSON HTTPS en https://www.wama.cloud.

Esta página describe la autenticación con claves API, el contexto multi-tenant del punto de venta, la paginación y los errores. Para los campos de solicitud y respuesta, abre la referencia OpenAPI interactiva (pantalla completa).

Primeros pasos

1. Crea una clave API en la app web de WAMA (Configuración → Integraciones). Prefiere solo lectura si tu integración no necesita escribir datos.
2. Llama a /api/** con el encabezado Authorization: Bearer <api_key> (o X-Api-Key).
3. Usa la referencia API interactiva para los campos de solicitud/respuesta.

URL base: https://www.wama.cloud

Autenticación

Crear una clave API

1. Inicia sesión en WAMA en el navegador como administrador de la cuenta (ROLE_USER / Administrador).
2. Abre Configuración → Integraciones.
3. Elige Crear clave API, define un nombre, el punto de venta al que se vincula la clave, el alcance y una fecha de caducidad opcional.
4. Copia la clave de inmediato: el secreto completo se muestra solo una vez.

Formato de la clave:

wama_<publicId>_<secret>

Guárdala como una contraseña (variable de entorno o gestor de secretos). Nunca subas claves a repositorios públicos ni las pegues en tickets abiertos.

Alcances (scopes)

Prefiere solo lectura para informes, sincronización y asistentes de IA, salvo que necesites escritura.

Llamar a la API

Envía la clave como encabezado HTTP en cada solicitud:

Authorization: Bearer wama_YOUR_PUBLIC_ID_YOUR_SECRET

Alias opcional (misma clave):

X-Api-Key: wama_YOUR_PUBLIC_ID_YOUR_SECRET

Si hay un JWT Authorization: Bearer … y también X-Api-Key, prevalece el JWT y se ignora X-Api-Key.

Ejemplo:

curl -X GET 'https://www.wama.cloud/api/products' \
  -H 'Authorization: Bearer wama_YOUR_PUBLIC_ID_YOUR_SECRET' \
  -H 'Accept: application/json'

Equivalente con X-Api-Key:

curl -X GET 'https://www.wama.cloud/api/products' \
  -H 'X-Api-Key: wama_YOUR_PUBLIC_ID_YOUR_SECRET' \
  -H 'Accept: application/json'

Revocar o rotar

Revoca las claves en Configuración → Integraciones. Las claves revocadas o caducadas devuelven 401. Para rotar, crea una nueva clave, actualiza el cliente y revoca la anterior.

Las claves API no pueden crear, listar ni revocar otras claves: gestiona las claves solo desde la app web (sesión de usuario).

Punto de venta (multi-tenant)

El inventario, las ventas y los datos relacionados pertenecen a un punto de venta (POS).

Cada clave API queda vinculada a un POS al crearla. Las solicitudes autenticadas con esa clave usan siempre ese POS: no cambies de POS con POST /api/point-of-sales/... cuando uses una clave API.

Crea una clave distinta por almacén/tienda si necesitas varios contextos POS.

Paginación

Los endpoints de listado aceptan parámetros de paginación de Spring Data:

Las respuestas de listado correctas incluyen:

Errores

La mayoría de los fallos devuelven JSON con esta forma:

{
  "message": "error.validation",
  "description": "Optional human-readable text",
  "fieldErrors": [
    {
      "objectName": "productDTO",
      "field": "barcode",
      "message": "NotNull",
      "defaultMessage": "must not be null"
    }
  ]
}

Los errores de dominio parametrizados pueden devolver { "message": "...", "params": ["..."] }.

Resultados habituales de autenticación:

Convenciones

• Cuerpos JSON en solicitud y respuesta (Content-Type: application/json)
• Fechas en ISO-8601 con offset (p. ej. 2026-03-15T10:30:00.000Z)
• Importes como decimales, con objetos de moneda cuando corresponda
• Los id los asigna el servidor; omítelos (o envía null) al crear

Ejemplo: listar productos

curl 'https://www.wama.cloud/api/products?page=0&size=20&sort=timeModified,desc' \
  -H 'Authorization: Bearer wama_YOUR_PUBLIC_ID_YOUR_SECRET'

Referencia OpenAPI

Consulta todos los endpoints públicos: