# API

{% embed url="<https://www.boxhero.io/en/blog/boxhero-open-api-integrate-inventory-data>" %}

***

## **Riferimento API**

Per la documentazione dettagliata degli endpoint, visita: <https://rest.boxhero.io/docs/api>

***

## Endpoint

Tutte le richieste API devono essere indirizzate al seguente URL base:\ <mark style="color:blu;"><https://rest.boxhero-app.com></mark>

## **Autenticazione**

Tutte le richieste API devono includere un <mark style="color:blu;">**Authorization**</mark> header con un <mark style="color:blu;">**token Bearer**</mark>:

```
Authorization: Bearer {API_TOKEN}
```

Per ottenere un token API:

1. Accedi al tuo account BoxHero su Desktop (Web).
2. Vai a <mark style="color:blu;">**`Impostazioni`**</mark> > <mark style="color:blu;">**`Integrazioni`**</mark>.
3. Genera un nuovo token API.

## **Invio delle richieste**

Ecco una richiesta API di esempio per recuperare i prodotti.

```bash
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 ripristino 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 un fallimento 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:**

```json
{
  "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

<table><thead><tr><th width="252">Tipo</th><th>Descrizione</th></tr></thead><tbody><tr><td>/errors/not-found</td><td>Risorsa richiesta non trovata (ad es. un elemento con un ID specifico non esiste).</td></tr><tr><td>/errors/invalid-request</td><td>Parametri non validi nella richiesta.</td></tr><tr><td>/errors/invalid-team-mode</td><td>La richiesta non può essere elaborata nell'attuale modalità del team (ad es. utilizzando l' <em>location</em> lookup API in <em>Modalità Base</em>).</td></tr><tr><td>/errors/tokens/required</td><td>Token API mancante.</td></tr><tr><td>/errors/tokens/invalid</td><td>Token API non valido (ad es. il token API è scaduto).</td></tr><tr><td>/errors/too-many-requests</td><td>Hai superato il limite di frequenza.</td></tr><tr><td>/errors/unhandled</td><td>Errore lato server non risolto.</td></tr><tr><td>/errors/core/usage-limit-exceeded</td><td>Limite di utilizzo raggiunto. È necessario passare a un piano superiore.</td></tr></tbody></table>

## Paginazione

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

{% hint style="info" %}
Per determinare se la paginazione è necessaria, controlla se i parametri relativi alla paginazione sono presenti nel corpo della richiesta dell'endpoint nella documentazione API.
{% endhint %}

#### **Parametri di paginazione**

* `has_more` : Un 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={valore del cursore ricevuto}` 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](https://docs-en.boxhero.io/etc/contact). Accogliamo volentieri il tuo feedback per miglioramenti dell'API e richieste di nuove funzionalità.