STORES API

L'API STORES permet à vos applications tierces d'accéder aux données que vous avez décidé d'exposer depuis votre compte VytarStores : stock en temps réel, liste des clients et sous-comptes, et toute ressource future que nous choisirons d'ouvrir. Elle est conçue pour une intégration simple — trois variables de configuration suffisent.

Base URL : https://open.vytarsstores.com

Trois variables de configuration

Variable	Exemple	Description
STORES_BASE_URL	https://open.vytarsstores.com	URL de base de l'API publique
STORES_APPID	MonEntreprise	Nom d'utilisateur du compte grossiste ou client (champ `nom` du compte)
STORES_SECRET_KEY	aB3kXz9mRp… (50 car.)	Clé secrète permanente générée automatiquement à la création du compte

Routes disponibles

Méthode	Route	Description
GET	/api/stores/stock/	Stock complet, groupé par entrepôt
GET	/api/stores/clients/	Clients (si grossiste) ou sous-comptes (si client)

Exemple minimal

# Récupérer le stock avec les trois variables
STORES_BASE_URL=https://open.vytarsstores.com
STORES_APPID=MonEntreprise
STORES_SECRET_KEY=aB3kXz9mRp...

curl -H "X-Stores-AppId: $STORES_APPID" \
     -H "X-Stores-Key: $STORES_SECRET_KEY" \
     $STORES_BASE_URL/api/stores/stock/

Authentification

Chaque requête vers l'API STORES doit inclure deux en-têtes HTTP. Ces valeurs correspondent aux variables STORES_APPID et STORES_SECRET_KEY de votre compte.

En-têtes requis

En-tête HTTP	Valeur	Description
X-Stores-AppId	= STORES_APPID	Nom d'utilisateur du compte (`nom` du grossiste ou client)
X-Stores-Key	= STORES_SECRET_KEY	Clé secrète permanente de 50 caractères

Ces identifiants doivent toujours être transmis dans les en-têtes HTTP, jamais dans l'URL. Les paramètres d'URL apparaissent dans les logs serveur et les proxys — ils peuvent être exposés accidentellement.

Où trouver vos identifiants

Votre STORES_APPID est le nom d'utilisateur avec lequel vous vous connectez à VytarStores. Votre STORES_SECRET_KEY est générée automatiquement à la création de votre compte et est disponible dans votre profil administrateur.

Exemple complet

# Configuration dans votre application
STORES_BASE_URL = "https://open.vytarsstores.com"
STORES_APPID    = "MonEntreprise"       # = votre nom d'utilisateur VytarStores
STORES_SECRET_KEY = "aB3kXz9mRp..."       # = clé secrète 50 caractères

# Utilisation dans une requête
curl -H "X-Stores-AppId: MonEntreprise" \
     -H "X-Stores-Key: aB3kXz9mRp..." \
     https://open.vytarsstores.com/api/stores/stock/

Erreur d'authentification

# Si les en-têtes sont absents
HTTP 400 → { "error": "Headers manquants : X-Stores-AppId et X-Stores-Key requis" }

# Si APPID ou KEY incorrects
HTTP 401 → { "error": "Identifiants invalides" }

Stock

Retourne l'ensemble du stock disponible, groupé par entrepôt. Disponible pour les comptes grossiste et client. Supporte le polling efficace via ?since=.

GET /api/stores/stock/ X-Stores-AppId · X-Stores-Key

Paramètres optionnels

Paramètre	Type	Description
since	ISO 8601	Si fourni et qu'aucune mise à jour n'a eu lieu depuis cette date, retourne `{"changed": false}` sans données

Exemple — requête simple

curl -H "X-Stores-AppId: MonEntreprise" \
     -H "X-Stores-Key: aB3kXz9mRp..." \
     https://open.vytarsstores.com/api/stores/stock/

Exemple — avec polling

curl -H "X-Stores-AppId: MonEntreprise" \
     -H "X-Stores-Key: aB3kXz9mRp..." \
     "https://open.vytarsstores.com/api/stores/stock/?since=2024-01-15T10:30:00Z"

Réponse — données disponibles

{
  "owner": "MonEntreprise",
  "data_at": "2024-01-15T10:30:00Z",  // à utiliser comme valeur ?since= au prochain appel
  "entrepots": [
    {
      "entrepot_id": 1,
      "entrepot_nom": "Dépôt Central",
      "lots": [
        {
          "produit": "Produit A",
          "quantite": 100,
          "prix_achat": 5000,
          "date_entree": "2024-01-10T08:00:00Z"
        }
      ]
    }
  ]
}

Réponse — rien n'a changé depuis since

{
  "changed": false,
  "checked_at": "2024-01-15T10:35:00Z"
}

Clients

Retourne les entités liées au compte authentifié. Un grossiste obtient la liste de ses clients avec photos, localisation GPS et ristournes. Un client obtient la liste de ses sous-comptes (utilisateurs).

GET /api/stores/clients/ X-Stores-AppId · X-Stores-Key

Paramètres optionnels

Paramètre	Type	Description
since	ISO 8601	Polling — retourne `{"changed": false}` si aucun changement depuis cette date

Exemple

curl -H "X-Stores-AppId: MonEntreprise" \
     -H "X-Stores-Key: aB3kXz9mRp..." \
     https://open.vytarsstores.com/api/stores/clients/

Réponse (compte grossiste)

{
  "owner": "MonEntreprise",
  "owner_type": "grossiste",
  "data_at": "2024-01-15T10:30:00Z",
  "clients": [
    {
      "client_id": 2,
      "nom": "ClientABC",
      "type": "natif",
      "ristourne": 5.0,
      "photos": {
        "profil": "/media/photos/profil_client.jpg",
        "emplacement": null,
        "entrepots": [{ "id": 3, "nom": "Dépôt Sud", "photo": "/media/..." }]
      },
      "localisation": {
        "lat": 3.8724, "lng": 11.5175,
        "entrepots": [{ "id": 3, "nom": "Dépôt Sud", "lat": 3.85, "lng": 11.50, "adresse": "Rue..." }]
      }
    }
  ]
}

Réponse (compte client)

{
  "owner": "ClientABC",
  "owner_type": "client",
  "data_at": "2024-01-15T10:30:00Z",
  "utilisateurs": [
    {
      "utilisateur_id": 5,
      "nom": "Vendeur01",
      "type": "natif",
      "photos": { "profil": null, "entrepots": [] },
      "localisation": { "lat": null, "lng": null, "entrepots": [] }
    }
  ]
}

Polling avec `?since=`

Pour éviter de transférer des données inutiles à chaque appel, passez la valeur data_at de la dernière réponse en paramètre ?since=. Si aucune mise à jour n'a eu lieu depuis cette date, le serveur répond instantanément sans données.

Fonctionnement

# 1er appel — pas de ?since, on récupère toutes les données
curl -H "X-Stores-AppId: MonEntreprise" \
     -H "X-Stores-Key: aB3kXz9mRp..." \
     https://open.vytarsstores.com/api/stores/stock/

# → réponse contient "data_at": "2024-01-15T10:30:00Z"

# Appel suivant — on passe data_at en ?since=
curl -H "X-Stores-AppId: MonEntreprise" \
     -H "X-Stores-Key: aB3kXz9mRp..." \
     "https://open.vytarsstores.com/api/stores/stock/?since=2024-01-15T10:30:00Z"

# Si rien n'a changé → réponse légère sans données
{ "changed": false, "checked_at": "2024-01-15T10:35:00Z" }

# Si le stock a changé → réponse complète avec nouveau data_at
{ "data_at": "2024-01-15T10:34:12Z", "entrepots": [...] }

Boucle recommandée (pseudo-code)

last_sync = null

loop every 30 seconds:
    url = STORES_BASE_URL + "/api/stores/stock/"
    if last_sync:
        url += "?since=" + last_sync

    res = GET(url, headers={
        "X-Stores-AppId": STORES_APPID,
        "X-Stores-Key":   STORES_SECRET_KEY
    })

    if res["changed"] != false:
        last_sync = res["data_at"]
        update_local_stock(res["entrepots"])

Le paramètre ?since= accepte tout format ISO 8601 valide : 2024-01-15T10:30:00Z, 2024-01-15T10:30:00+01:00, etc.

Réponses d'erreur

Toutes les erreurs retournent un objet JSON avec un champ error décrivant la cause.

Codes HTTP

Code	Corps JSON	Cause
400	{"error": "Headers manquants..."}	En-tête `X-Stores-AppId` ou `X-Stores-Key` absent de la requête
401	{"error": "Identifiants invalides"}	Combinaison STORES_APPID / STORES_SECRET_KEY incorrecte
405	—	Méthode HTTP incorrecte (seul GET est accepté sur ces routes)
500	{"error": "..."}	Erreur serveur interne — contacter l'administrateur VytarStores

Exemple de gestion d'erreur