API

Guida API REST WAMA

Integra i tuoi sistemi con WAMA usando l’API JSON HTTPS su https://www.wama.cloud.

Questa pagina descrive l’autenticazione con chiavi API, il contesto multi-tenant del punto vendita, la paginazione e gli errori. Per i campi di richiesta e risposta apri il riferimento OpenAPI interattivo (a schermo intero).

Per iniziare

1. Crea una chiave API nell’app web WAMA (Impostazioni → Integrazioni). Preferisci sola lettura se l’integrazione non deve scrivere dati.
2. Chiama /api/** con l’header Authorization: Bearer <api_key> (oppure X-Api-Key).
3. Usa il riferimento API interattivo per i campi di richiesta/risposta.

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

Autenticazione

Creare una chiave API

1. Accedi a WAMA nel browser come amministratore dell’account (ROLE_USER / Amministratore).
2. Apri Impostazioni → Integrazioni.
3. Scegli Crea chiave API, imposta un nome, il punto vendita a cui legare la chiave, l’ambito e una data di scadenza opzionale.
4. Copia subito la chiave: il segreto completo viene mostrato una sola volta.

Formato della chiave:

wama_<publicId>_<secret>

Conservala come una password (variabile d’ambiente o secret manager). Non inserire mai le chiavi nel codice in repository pubblici né nei ticket aperti.

Ambiti (scope)

Preferisci sola lettura per report, sync e assistenti AI, a meno che non servano scritture.

Chiamare l’API

Invia la chiave come header HTTP in ogni richiesta:

Authorization: Bearer wama_YOUR_PUBLIC_ID_YOUR_SECRET

Alias opzionale (stessa chiave):

X-Api-Key: wama_YOUR_PUBLIC_ID_YOUR_SECRET

Se sono presenti sia un JWT Authorization: Bearer … sia X-Api-Key, prevale il JWT e X-Api-Key viene ignorato.

Esempio:

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'

Revocare o ruotare

Revoca le chiavi da Impostazioni → Integrazioni. Chiavi revocate o scadute restituiscono 401. Per ruotare, crea una nuova chiave, aggiorna il client e revoca quella vecchia.

Le chiavi API non possono creare, elencare o revocare altre chiavi: gestiscile solo dall’app web (sessione utente).

Punto vendita (multi-tenant)

Inventario, vendite e dati correlati appartengono a un punto vendita (POS).

Ogni chiave API è legata a un POS alla creazione. Le richieste autenticate con quella chiave usano sempre quel POS: non cambiare POS con POST /api/point-of-sales/... quando usi una chiave API.

Crea una chiave distinta per ogni magazzino/punto vendita se ti servono più contesti.

Paginazione

Gli endpoint di lista accettano i parametri di paginazione Spring Data:

Le risposte di lista di successo includono:

Errori

La maggior parte degli errori restituisce JSON di questo tipo:

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

Gli errori di dominio parametrizzati possono restituire { "message": "...", "params": ["..."] }.

Esiti tipici di autenticazione:

Convenzioni

• Corpi JSON in richiesta e risposta (Content-Type: application/json)
• Date in ISO-8601 con offset (es. 2026-03-15T10:30:00.000Z)
• Importi come decimali, con oggetti valuta dove previsto
• Gli id sono assegnati dal server; omettili (o invia null) in creazione

Esempio: elenco prodotti

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

Riferimento OpenAPI

Sfoglia tutti gli endpoint pubblici: