# API

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

***

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

Pour la 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 <mark style="color:bleu;">**Authorization**</mark> en-tête avec un <mark style="color:bleu;">**jeton Bearer**</mark>:

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

Pour obtenir un jeton API :

1. Connectez-vous à votre compte BoxHero sur le bureau (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.

## **Faire des 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 débit

Pour garantir la stabilité du système, nous imposons les limites de débit suivantes :

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

Une fois la limite de débit 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 nombre de requêtes

***

## Réponses

### Succès

Les réponses avec des codes d’état HTTP dans la plage 200 indiquent un traitement API réussi.

### Erreur

Les codes d’état dans les plages 400 ou 500 indiquent des échecs de requêtes API :

* Plage 400 : erreur côté client due aux informations fournies avec la requête (par ex. paramètres requis 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 :** Pointe vers l’identifiant de la requête associée à l’erreur.
* **autres :** Des champs supplémentaires peuvent être inclus pour fournir des informations supplémentaires, 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 ID 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. l’utilisation de l’API de recherche <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>Limite de débit 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 forfait requise.</td></tr></tbody></table>

## Pagination

Pour les points de terminaison renvoyant de grands ensembles de données (par ex. listes d’éléments, 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 s’il existe davantage de données au-delà de la page actuelle.
* `cursor` : Fournit la valeur du curseur pour récupérer la page suivante.

#### **Récupérer la page suivante**

* Vérifiez si `has_more` est `true`. Cela signifie qu’une autre page est disponible.
* Si `true`, 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 `false` 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 accueillons volontiers vos retours pour des améliorations de l’API et de nouvelles demandes de fonctionnalités.