Gestire i client OAuth2

curl -X POST https://shop.de/xpanel/xoport/oauth/token 
  -H "Content-Type: application/x-www-form-urlencoded" 
  -d "grant_type=client_credentials" 
  -d "client_id=xoc_abc123..." 
  -d "client_secret=xos_def456..."

Risposta

{
  "access_token": "xoat_eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "products:read products:write categories:read"
}

Errore all'endpoint del token

L'endpoint del token risponde nel formato OAuth2 con error e error_description, verificati in questo ordine:

In assenza di scope, sono validi tutti gli ambiti del client.

curl -X GET https://shop.de/xpanel/xoPort/me 
  -H "Authorization: Bearer xoat_eyJhbGciOi..."

Risposta

{
  "success": true,
  "api_version": "2.122.11",
  "type": "client_info",
  "data": {
    "client_id": "xoc_abc123...",
    "client_name": "Mein API Client",
    "scopes": ["products:read", "products:write", "categories:read"],
    "rate_limit": 5000,
    "rate_limit_window": 3600,
    "rate_limit_remaining": 4987,
    "rate_limit_reset": 1792327500,
    "token_expires_at": "2026-10-18 15:00:00",
    "token_created_at": "2026-10-18 14:00:00",
    "client_created_at": "2026-01-15 10:30:00",
    "client_last_used_at": "2026-10-18 14:22:15"
  },
  "timestamp": "2026-10-18 14:22:16"
}

A partire dalla versione v2.122.11 rate_limit_window, la durata della finestra di conteggio è espressa in secondi (sempre 3600). rate_limit_remaining e rate_limit_reset hanno gli stessi valori delle intestazioni X-RateLimit-Remaining e X-RateLimit-Reset della stessa risposta; la richiesta a /me viene conteggiata. Per i client senza limite di richieste, entrambi i valori sono null.

Il limite di richieste si applica per client, non per token: tutti i token e i processi di un client condividono un unico contatore. Il conteggio avviene in una finestra mobile di 3600 secondi; un posto si libera non appena la richiesta più vecchia conteggiata risale a più di un'ora fa. Il valore (rate_limit, richieste per finestra) va impostato nel backend del client; GET /me lo mostra (null significa illimitato, 0 ha lo stesso effetto).

Impostazioni predefinite (a partire dalla versione 4.9.17; in precedenza, un campo vuoto indicava "illimitato"): per l’amministratore, il campo è preimpostato a 5000 al momento della creazione; non è possibile impostare un valore superiore e, se salvato vuoto, viene considerato pari a 5000. Un valore superiore a 5000 impostato da XONIC rimane valido fintanto che il campo non viene modificato. A partire dalla versione 4.9.174 di Shop, la funzione «Modifica client» mostra, per un client illimitato, un campo vuoto con l’indicazione «Illimitato (impostato da XONIC)»; se salvato vuoto, rimane illimitato; un numero fino a 5000 lo limita, mentre solo XONIC può riportarlo a illimitato. ⚠️ Fino alla versione 4.9.173 di Shop, a un cliente illimitato veniva assegnato il valore 5000 non appena l’amministratore lo salvava, anche se venivano modificati solo il nome o la nota. Nell’amministratore XONIC il campo è vuoto, e «vuoto» in quel contesto significa «illimitato». ⚠️ Fino alla versione Shop 4.9.173, durante la creazione con il campo vuoto veniva comunque generato un client con valore 5000 se la colonna nel database aveva il valore predefinito 5000 (ad esempio dopo una reinstallazione a partire dalla versione Shop 4.9.17). Verificate questi valori dopo la creazione in GET /me → rate_limit. Nelle versioni di Shop dalla 4.9.17 alla 4.9.167, ogni controllo HealthCheck e ogni aggiornamento reimpostano un client illimitato a 5000; a partire dalla versione 4.9.168, il valore “illimitato” rimane invariato. Una modifica del limite ha effetto immediato, anche per i token attivi.

Quota in ogni risposta A partire dalla v2.122.11

Ogni risposta a una richiesta con un token valido proveniente da un client con limite di richieste contiene tre intestazioni:

• Con intestazioni: dati, risposte di errore come 400, 403 o 404, download di file, richieste XML con token e la risposta 429 stessa.
• Senza intestazioni: client senza limite di richieste, richieste senza token valido (401), richieste XML senza token o provenienti da un indirizzo con autorizzazione IP dell’interfaccia XML e dell’endpoint del token.
• Il resto vale per tutti i processi del client nel loro insieme: ciò che viene indicato come risposta potrebbe essere già stato utilizzato da un processo parallelo.
• I negozi fino alla versione 4.9.170 non inviano queste intestazioni. La loro assenza non significa «illimitato»: in tal caso, consultare GET /me.

Se il limite viene superato, l’API risponde con HTTP 429 e Retry-After; si veda l’esempio nella sezione Gestione degli errori.

Limite proprio sull’endpoint del token

POST /oauth/token ha un proprio limite: 30 richieste in 300 secondi per client_id, anch’esso mobile; vengono conteggiate anche le richieste con secret errato. In tal caso viene restituito un codice di stato HTTP 429 con rate_limit_exceeded. A partire dalla versione v2.122.11, Retry-After indica i secondi che mancano alla prossima accettazione (da 1 a 300); in precedenza il valore era fisso a 300. L’endpoint del token non invia X-RateLimit-*. Un token è valido per un’ora: recuperatelo una sola volta e trasmettetelo a tutti i processi.

Log di utilizzo

Nel backend, il log di utilizzo mostra per ogni client le ultime 1000 richieste con richiesta e risposta. Non sono inclusi gli interruzioni dell’esportazione con codice HTTP 400 prima dell’esecuzione di una query (errori di filtro, di scorrimento e di percorso), i documenti giustificativi e i singoli allegati dei ticket, la risposta 429 e le richieste XML. Tuttavia, queste richieste vengono comunque conteggiate ai fini del limite di richieste, ad eccezione del codice di risposta 429 e delle richieste XML senza token.

A partire dalla v2.119.0, l’API REST richiede sempre un token OAuth2 e si applicano i relativi ambiti (scopes). L’autorizzazione IP dell’interfaccia XML (XML_PORT_IP_FILTER) non dà diritto all’accesso all’API REST.

Inoltre, è possibile limitare l’accesso a indirizzi fissi. Se il campo XOPORT_REST_IP_LIST è compilato, una richiesta deve provenire da un indirizzo presente nell’elenco e contenere un token valido; l’elenco non sostituisce mai il token. Le richieste provenienti da altri indirizzi ricevono il messaggio di errore 403 con reason: deny_ip_not_listed.