Revised:
1. Di cosa si tratta
L'API REST di WareRushAI consente ad altri programmi di leggere i dati di un'azienda: prodotti, giacenze per ubicazione, ordini, prodotti con dati mancanti ed errori di inserzione sui marketplace. È in sola lettura in questa versione e poggia sugli stessi servizi e controlli dei permessi dell'app web e del connettore MCP. L'indirizzo di base è https://app.warerushai.com/api/v1. L'API viene aperta gradualmente: finché non sarà attivata per la piattaforma, ogni chiamata restituirà 404 e non sarà possibile creare chiavi.
2. Creare una chiave API
Un proprietario o amministratore apre Impostazioni, poi Integrazioni, quindi Chiavi API, assegna un nome alla chiave, sceglie i permessi (catalog.read, inventory.read, orders.read, account.read), una scadenza e un limite al minuto, e la crea. La chiave completa inizia con wra_live_ e viene mostrata una sola volta. WareRushAI memorizza solo un hash unidirezionale e i primi caratteri, quindi una chiave smarrita non può essere recuperata: creane una nuova. Puoi revocare una chiave in qualsiasi momento o ruotarla: la nuova chiave viene mostrata una sola volta e quella precedente continuerà a funzionare per 24 ore.
3. Autenticazione
Invia la chiave nell'intestazione Authorization: Authorization: Bearer wra_live_... tramite HTTPS. Non inserire mai la chiave nell'indirizzo web; una richiesta che lo fa viene rifiutata con key_in_url. Esempio: curl -H "Authorization: Bearer $WRA_KEY" "https://app.warerushai.com/api/v1/products?limit=20". Sono accettati anche i token di accesso OAuth 2.1 del connettore MCP, con i permessi approvati dall'utente.
4. Endpoint
GET /me (la chiave, i relativi limiti e l'utilizzo odierno), GET /products (ricerca ed elenco, con query, limit, cursor), GET /products/{id}, GET /locations, GET /inventory (righe di giacenza, paginate), GET /inventory/summary, GET /orders (con updated_since, status, source, limit, cursor), GET /missing-data e GET /marketplace-errors (con channel). Ogni endpoint richiede il permesso corrispondente: catalog.read per prodotti, dati mancanti ed errori dei marketplace, inventory.read per ubicazioni e inventario, orders.read per gli ordini. È supportato solo il metodo GET; gli altri metodi restituiscono 405.
5. Paginazione e polling
Gli elenchi restituiscono data, next_cursor e has_more, con un massimo di 50 elementi per pagina (limit da 1 a 50, predefinito 20). Passa nuovamente next_cursor come cursor per ottenere la pagina successiva. Per i trigger di polling di Zapier, Make e n8n, chiama GET /orders?updated_since=2026-11-15T08:00:00Z e memorizza l'orario dell'ultimo polling riuscito: riceverai gli ordini creati o modificati da quel momento, dai più recenti ai meno recenti.
6. Limiti ed errori
Ogni chiave prevede un limite al minuto (predefinito 60, massimo 600) e un limite giornaliero facoltativo. Ciascuna azienda ha inoltre una quota giornaliera in base al piano: per impostazione predefinita 1 000 chiamate per Starter, 10 000 per Business e 100 000 per Pro. Quando viene raggiunto un limite, l'API risponde con 429 e un'intestazione Retry-After. Le intestazioni X-RateLimit-Limit, X-RateLimit-Remaining, X-Daily-Limit e X-Daily-Remaining mostrano la quota rimanente. Gli errori hanno sempre la struttura {"error":{"code","message","request_id"}}; cita il request_id quando contatti l'assistenza. Codici frequenti: invalid_api_key (401), insufficient_scope (403), not_found (404), invalid_parameter (400), rate_limited e daily_quota_exceeded (429).
7. Descrizione OpenAPI
La descrizione OpenAPI 3.1 leggibile da macchina è disponibile all'indirizzo https://app.warerushai.com/api/v1/openapi.json e non richiede alcuna chiave. Importala in Postman, Zapier, Make, n8n o in un assistente AI per ottenere tutti gli endpoint, i parametri e le strutture delle risposte. Le modifiche vengono apportate senza alterare i campi esistenti; la versione è /api/v1.
8. Sicurezza
Le chiavi appartengono esattamente a un'azienda e vengono verificate a ogni chiamata; una chiave non può mai leggere i dati di un'altra azienda e smette di funzionare se l'amministratore che l'ha creata lascia l'azienda. Le chiavi non compaiono mai nei registri o nei messaggi di errore e il registro delle chiamate mostra solo percorso, stato e orario. I dati finanziari, come i prezzi di acquisto, non sono esposti da questa API.
