# API

<figure><img src="/files/f8707b69f9d3bdd4b5e75808f2264b237eac7249" alt=""><figcaption></figcaption></figure>

***

## **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 **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 <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 rimanente (in secondi) 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 errori 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.
* **others :** 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 query richiesta non può essere elaborata nell'attuale modalità del team (ad es. utilizzo dell'API di ricerca di <em>location</em> 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>Limite di frequenza superato.</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 set di dati di grandi dimensioni (ad es. elenchi di elementi, elenchi di transazioni), la vista elenco dell'API limita il numero di elementi restituiti in una singola richiesta tramite la paginazione. Usiamo una paginazione basata su cursore:

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

#### **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**

* Verifica 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 finché `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 con piacere il tuo feedback per miglioramenti dell'API e richieste di nuove funzionalità.

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://www.boxhero.io/docs/documentation/it/integrazioni/open-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.