API

L'API di BoxHero consente agli sviluppatori di integrare le nostre funzionalità di gestione dell'inventario con applicazioni esterne per un recupero e una interazione dei dati efficienti.

BoxHero’s API: A Simple Way to Integrate Your Inventory DataBoxHero Blog

---

Riferimento API

Per la documentazione dettagliata degli endpoint, visita: https://rest.boxhero-app.com/docs/api

---

Endpoint

Tutte le richieste API devono essere indirizzate al seguente URL base: https://rest.boxhero-app.com

Autenticazione

Tutte le richieste API devono includere un Authorization header con un Bearer token:

Authorization: Bearer {API_TOKEN}

Per ottenere un token API:

1. Accedi al tuo account BoxHero sul Desktop (Web).

2. Vai a Impostazioni > Integrazioni.

3. Genera un nuovo token API.

Invio delle richieste

Ecco un esempio di richiesta API per recuperare i prodotti.

curl -X 'GET' \
  'https://rest.boxhero-app.com/v1/items?location_ids=12345&location_ids=34567&limit=100' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer test-api-token-123'

Limiti di frequenza

Per garantire la stabilità del sistema, imponiamo i seguenti limiti di frequenza:

• 5 query al secondo per ciascun endpoint.

Una volta raggiunto il limite di frequenza, vedrai un messaggio di errore con quanto segue:

• X-Ratelimit-Limit - Numero massimo di query al minuto

• X-Ratelimit-Remaining - Query rimanenti

• X-Ratelimit-Reset - Tempo (in secondi) rimanente fino al reset del conteggio delle query

---

Risposte

Successo

Le risposte con codici di stato HTTP nell'intervallo 200 indicano un'elaborazione API riuscita.

Errore

I codici di stato nell'intervallo 400 o 500 indicano fallimenti della richiesta API:

• Intervallo 400: errore lato client dovuto alle informazioni fornite con la richiesta (ad es. parametri obbligatori mancanti).

• Intervallo 500: errore lato server.

Esempio di risposta di errore:

{
  "id": "ex_ku3gij67k9xzc8ef6r5esyu5",
  "type": "/errors/tokens/invalid",
  "title": "Il token di autenticazione non è valido. Fornisci un token valido.",
  "correlation_id": "rq_z4g7dh55ykol7v2cx6homkpd",
  "given": "invalid-token-123"
}

• id : Un ID univoco per identificare l'errore.

• type : Un codice sotto forma di URL che identifica il tipo di errore.

• title : Fornisce il contenuto dell'errore in forma leggibile.

• correlation_id : Indica l'ID della richiesta associata all'errore.

• altro : Possono essere inclusi campi aggiuntivi per fornire ulteriori informazioni, come "given" nell'esempio.

Tipi di errore comuni

Tipo	Descrizione
/errors/not-found	Risorsa richiesta non trovata (ad es., l'elemento con un ID specifico non esiste).
/errors/invalid-request	Parametri non validi nella richiesta.
/errors/invalid-team-mode	La query richiesta non può essere elaborata nell'attuale modalità del team (ad es., usando la ubicazione API di lookup in Modalità Base).
/errors/tokens/required	Token API mancante.
/errors/tokens/invalid	Token API non valido (ad es., il token API è scaduto).
/errors/too-many-requests	Limite di frequenza superato.
/errors/unhandled	Errore lato server non risolto.
/errors/core/usage-limit-exceeded	Limite di utilizzo raggiunto. È necessario passare a un piano superiore.

Paginazione

Per gli endpoint che restituiscono grandi set di dati (ad es. elenchi di elementi, elenchi di transazioni), l'API della vista elenco limita il numero di elementi restituiti in una singola richiesta tramite la paginazione. Usiamo la paginazione basata su cursore:

Per determinare se è necessaria la paginazione, verifica se i parametri relativi alla paginazione sono presenti nel corpo della richiesta dell'endpoint nella documentazione API.

Parametri di paginazione

• has_more : Un valore booleano che indica se esistono altri dati oltre la pagina corrente.

• cursor : Fornisce il valore del cursore per recuperare la pagina successiva.

Recupero della pagina successiva

• Controlla se has_more è true. Significa che è disponibile un'altra pagina.

• Se true, invia un'altra richiesta includendo cursor={received cursor value} nei parametri. Questo restituirà i dati successivi.

• Ripeti fino a quando has_more è false per recuperare l'elenco completo.

---

Supporto e feedback

Se riscontri problemi o hai bisogno di funzionalità API aggiuntive, contatta il nostro team di supporto. Accogliamo volentieri il tuo feedback per miglioramenti dell'API e richieste di nuove funzionalità.