# API

<figure><img src="/files/8a2c7a71b0b4f6764b4c2ac46d3c768ce4f29170" alt=""><figcaption></figcaption></figure>

***

## **Référence de l’API**

Pour une documentation détaillée des points de terminaison, veuillez consulter : <https://rest.boxhero.io/docs/api>

***

## Point de terminaison

Toutes les requêtes API doivent être envoyées à l’URL de base suivante :\ <mark style="color:bleu;"><https://rest.boxhero-app.com></mark>

## **Authentification**

Toutes les requêtes API doivent inclure un **Authorization** **en-tête** avec un **Bearer** **jeton**:

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

Pour obtenir un jeton API :

1. Connectez-vous à votre compte BoxHero sur Desktop (Web).
2. Accédez à <mark style="color:bleu;">`Paramètres`</mark> > <mark style="color:bleu;">`Intégrations`</mark>.
3. Générez un nouveau jeton API.

## **Envoi de requêtes**

Voici un exemple de requête API pour récupérer des produits.

```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'
```

## Limites de taux

Afin d’assurer la stabilité du système, nous appliquons les limites de taux suivantes :

* 5 requêtes par seconde pour chaque point de terminaison.

Une fois la limite de taux atteinte, vous verrez un message d’erreur contenant les éléments suivants :

* `X-Ratelimit-Limit` - Nombre maximal de requêtes par minute
* `X-Ratelimit-Remaining` - Requêtes restantes
* `X-Ratelimit-Reset` - Temps (en secondes) restant avant la réinitialisation du compteur de requêtes

***

## Réponses

### Succès

Les réponses avec des codes de statut HTTP dans la plage 200 indiquent un traitement API réussi.

### Erreur

Les codes de statut dans la plage 400 ou 500 indiquent des échecs de requête API :

* Plage 400 : erreur côté client due aux informations fournies avec la requête (par ex., paramètres obligatoires manquants).
* Plage 500 : erreur côté serveur.

**Exemple de réponse d’erreur :**

```json
{
  "id": "ex_ku3gij67k9xzc8ef6r5esyu5",
  "type": "/errors/tokens/invalid",
  "title": "Le jeton d’authentification est invalide. Veuillez fournir un jeton valide.",
  "correlation_id": "rq_z4g7dh55ykol7v2cx6homkpd",
  "given": "invalid-token-123"
}
```

* **id :** Un identifiant unique pour identifier l’erreur.
* **type :** Un code sous forme d’URL qui identifie le type d’erreur.
* **title :** Fournit le contenu de l’erreur sous une forme lisible par l’humain.
* **correlation\_id :** Fait référence à l’identifiant de la requête associée à l’erreur.
* **autres :** Des champs supplémentaires peuvent être inclus pour fournir des informations additionnelles, telles que "*given*" dans l’exemple.

### Types d’erreurs courants

<table><thead><tr><th width="252">Type</th><th>Description</th></tr></thead><tbody><tr><td>/errors/not-found</td><td>Ressource demandée introuvable (par ex., un élément avec un identifiant spécifique n’existe pas).</td></tr><tr><td>/errors/invalid-request</td><td>Paramètres invalides dans la requête.</td></tr><tr><td>/errors/invalid-team-mode</td><td>La requête demandée ne peut pas être traitée dans le mode d’équipe actuel (par ex., utiliser l’API de recherche de <em>location</em> dans le <em>Mode Basique</em>).</td></tr><tr><td>/errors/tokens/required</td><td>Jeton API manquant.</td></tr><tr><td>/errors/tokens/invalid</td><td>Jeton API invalide (par ex., le jeton API a expiré).</td></tr><tr><td>/errors/too-many-requests</td><td>La limite de taux a été dépassée.</td></tr><tr><td>/errors/unhandled</td><td>Erreur côté serveur non résolue.</td></tr><tr><td>/errors/core/usage-limit-exceeded</td><td>Limite d’utilisation atteinte. Mise à niveau du plan requise.</td></tr></tbody></table>

## Pagination

Pour les points de terminaison renvoyant de grands ensembles de données (par ex., listes d’articles, listes de transactions), l’API de vue en liste limite le nombre d’éléments renvoyés dans une seule requête grâce à la pagination. Nous utilisons une pagination basée sur un curseur :

{% hint style="info" %}
Pour déterminer si la pagination est requise, vérifiez si des paramètres liés à la pagination sont présents dans le corps de la requête du point de terminaison dans la documentation de l’API.
{% endhint %}

#### **Paramètres de pagination**

* `has_more` : Un booléen qui indique si d’autres données existent au-delà de la page actuelle.
* `cursor` : Fournit la valeur du curseur pour récupérer la page suivante.

#### **Récupération de la page suivante**

* Vérifiez si `has_more` est `vrai`. Cela signifie qu’une autre page est disponible.
* Si `vrai`, envoyez une autre requête en incluant `cursor={received cursor value}` dans les paramètres. Cela renverra les données suivantes.
* Répétez jusqu’à ce que `has_more` est `faux` pour récupérer la liste complète.

***

## Support et retours

Si vous rencontrez des problèmes ou avez besoin de fonctionnalités API supplémentaires, veuillez contacter notre [équipe d’assistance](https://docs-en.boxhero.io/etc/contact). Nous apprécions vos retours pour l’amélioration de l’API et les nouvelles demandes de fonctionnalités.

{% 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/fr/integrations/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.