Connecter l'API REST

L'API REST d'Inventoria permet à des applications tierces d'interroger et de manipuler les données du parc — exports automatisés, intégrations métier, dashboards externes.

⏱Durée30–60 minutes👤RôleAdministrateur📊NiveauAvancé

Prérequis

• Vous disposez d'un compte avec le rôle Administrateur ou Super-administrateur
• Vous savez exécuter des requêtes HTTP (cURL, Postman, fetch…)
• Inventoria est accessible depuis l'environnement qui effectuera les appels

---

1

Générer un token API

Les appels API s'authentifient via un token Bearer personnel. Chaque token peut avoir des permissions restreintes à certaines ressources.

1. Connectez-vous à Inventoria
2. Cliquez sur votre avatar en haut à droite → Profil
3. Ouvrez l'onglet Tokens API
4. Cliquez sur Nouveau token
5. Donnez-lui un nom descriptif (ex : export-comptabilite, script-inventaire)
6. Sélectionnez les permissions nécessaires (lecture seule recommandée pour les intégrations)
7. Cliquez sur Créer

Token affiché une seule fois

Copiez et conservez le token immédiatement — il ne sera plus visible après fermeture de la fenêtre. En cas de perte, supprimez-le et créez-en un nouveau.

➜ Documentation Tokens API

2

Effectuer votre premier appel

Tous les endpoints sont préfixés par /api. L'authentification se fait via l'en-tête Authorization.

Tester la connexion — récupérer la liste des articles :

curl https://votre-instance.inventoria.app/api/v1/articles \
  -H "Authorization: Bearer VOTRE_TOKEN" \
  -H "Accept: application/json"

Réponse attendue :

{
  "data": [
    {
      "id": 1,
      "name": "MacBook Pro 14\" M3",
      "brand": "Apple",
      "category": "Informatique",
      "purchases_count": 3
    }
  ],
  "meta": {
    "current_page": 1,
    "total": 42
  }
}

Tester avec Postman

Créez une collection Postman avec une variable {{base_url}} et un en-tête d'environnement Authorization: Bearer {{token}} — vous n'aurez à saisir le token qu'une seule fois.

3

Parcourir les endpoints principaux

L'API couvre les ressources suivantes :

Ressource	Endpoint	Méthodes
Articles	/api/v1/articles	GET, GET /{id}, POST, PATCH, DELETE
Achats	/api/v1/purchases	GET, GET /{id}, POST, PATCH, DELETE
Inventaires	/api/v1/inventories	GET, GET /{id}, POST
Fournisseurs	/api/v1/suppliers	GET, GET /{id}, POST, PATCH, DELETE
Marques	/api/v1/brands	GET, GET /{id}
Catégories	/api/v1/categories	GET, GET /{id}
Lookup QR	/api/v1/scan/{code}	GET
Scan inventaire	/api/v1/inventories/{id}/scan	POST

Identifier un achat par son code QR :

curl https://votre-instance.inventoria.app/api/v1/scan/ABC12345 \
  -H "Authorization: Bearer VOTRE_TOKEN" \
  -H "Accept: application/json"

Filtrer les achats par article :

curl "https://votre-instance.inventoria.app/api/v1/purchases?article_id=5&per_page=50" \
  -H "Authorization: Bearer VOTRE_TOKEN" \
  -H "Accept: application/json"

4

Intégrer dans une application JavaScript

Exemple complet avec fetch — récupération paginée de tous les achats actifs :

const BASE_URL = 'https://votre-instance.inventoria.app/api';
const TOKEN = process.env.INVENTORIA_TOKEN;

async function fetchAllPurchases() {
  let page = 1;
  let allPurchases = [];

  while (true) {
    const res = await fetch(
      `${BASE_URL}/purchases?status=active&page=${page}&per_page=100`,
      { headers: { Authorization: `Bearer ${TOKEN}`, Accept: 'application/json' } }
    );

    if (!res.ok) throw new Error(`HTTP ${res.status}`);

    const { data, meta } = await res.json();
    allPurchases = allPurchases.concat(data);

    if (page >= meta.last_page) break;
    page++;
  }

  return allPurchases;
}

Stocker le token en variable d'environnement

Ne codez jamais le token en dur dans votre code source. Utilisez une variable d'environnement (process.env.INVENTORIA_TOKEN) ou un gestionnaire de secrets.

5

Scanner un code QR via l'API

L'endpoint POST /inventories/{id}/scan permet d'enregistrer un scan dans une session d'inventaire depuis une application tierce ou un terminal personnalisé.

curl -X POST https://votre-instance.inventoria.app/api/v1/inventories/3/scan \
  -H "Authorization: Bearer VOTRE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"code": "ABC12345"}'

Réponses possibles :

{ "status": "success", "message": "Article ajouté", "article": "MacBook Pro 14\" M3" }

{ "status": "warning", "message": "Déjà scanné", "article": "MacBook Pro 14\" M3" }

{ "status": "error", "message": "Code inconnu" }

Pour identifier un achat par son code sans l'enregistrer dans un inventaire :

curl https://votre-instance.inventoria.app/api/v1/scan/ABC12345 \
  -H "Authorization: Bearer VOTRE_TOKEN"

6

Gérer les erreurs et la pagination

Format d'erreur standard :

{
  "message": "Unauthenticated.",
  "status": 401
}

Pagination — tous les endpoints de liste sont paginés :

"meta": {
  "current_page": 1,
  "last_page": 5,
  "per_page": 20,
  "total": 98
}

Utilisez les paramètres page et per_page (max 100) pour parcourir les résultats. Implémentez un mécanisme de retry avec backoff exponentiel pour les environnements de production.

Rate limiting

L'API applique une limite de requêtes par token. En cas de 429 Too Many Requests, patientez avant de relancer vos appels.

➜ Référence API complète

---

Récapitulatif

1. Profil → Tokens API → Nouveau token (permissions minimales)
2. En-tête Authorization: Bearer <token> sur toutes les requêtes
3. Base URL : /api
4. Endpoints : articles, purchases, inventories, suppliers, scan
5. Pagination via page + per_page (max 100)
6. Token en variable d'environnement, jamais en dur

Endpoints les plus utilisés :

Cas d'usage	Endpoint
Export catalogue	GET /api/v1/articles
Liste des unités physiques	GET /api/v1/purchases
Données d'un inventaire	GET /api/v1/snapshots/{id}
Scan depuis terminal tiers	POST /api/v1/scan