Aller au contenu principal

Développeurs

API Marchand

Une API REST en lecture seule pour votre boutique VeeBoost : un contrat publié, une authentification par clé et une pagination prévisible — pensée pour des intégrations qui restent synchrones.

Un contrat unique, publié comme seule source de vérité

Votre boutique publie le contrat complet lisible par les machines (OpenAPI 3.1) : chaque endpoint, paramètre, réponse et code d'erreur de l'API marchand. Cette page pointe vers lui et ne recopie jamais les tables d'endpoints — le contrat ne peut pas dériver, votre intégration non plus.

Contrat publiéGET /openapi/v1.json

Démarrage rapide

Trois étapes pour votre première lecture catalogue :

  1. Créez une clé API dans votre admin (rubrique Développeurs) avec les scopes de lecture dont vous avez besoin. Elle commence par vbk_ et n'est affichée qu'une seule fois.
  2. Envoyez-la dans l’en-tête X-Api-Key à chaque requête — votre tenant est résolu depuis la clé, jamais depuis l’hôte.
  3. Appelez votre premier endpoint, par exemple GET /products, puis suivez le contrat pour tout le reste.

Authentification

Chaque requête porte votre clé dans l'en-tête X-Api-Key. La v1 offre exactement quatre scopes en lecture — produits, commandes, clients et livraisons de webhooks. Un scope manquant répond 403, une clé révoquée est refusée immédiatement. Gardez les clés côté serveur : elles n'ont jamais leur place dans un navigateur ou un dépôt public.

products:readorders:readcustomers:readwebhooks:read

Pagination

Les endpoints de liste paginent : parcourez-les avec le paramètre page et lisez l'enveloppe renvoyée avec chaque collection — elle indique où vous en êtes pour resynchroniser votre intégration sans deviner. Les paramètres exacts de chaque endpoint sont documentés dans le contrat.

Erreurs et limites de débit

Les erreurs renvoient un corps JSON structuré, parsable — jamais un paragraphe à gratter. Une réponse 429 est un contrat stable : toujours la même forme de corps, avec les en-têtes X-RateLimit-* et un Retry-After qui dit exactement quand revenir. Forcer ne débloque pas de données — reculez.

Clés sandbox

Durant la période de pré-lancement, les clés sandbox sont délivrées après validation par notre équipe et tournent avec un budget de débit dédié, séparé des clés de production — explorez l'API sur votre boutique sans toucher au trafic réel ni aux quotas.

Exemples par langage

Un extrait par plateforme, scopes de lecture uniquement : chacun récupère votre catalogue produits. Remplacez <api-base> par l’hôte API de votre boutique indiqué dans l’admin → rubrique Développeurs.

curl

curl -H "X-Api-Key: vbk_your_key" \
  "https://<api-base>/products?page=1"

JavaScript

async function listProducts(page = 1) {
  const res = await fetch("https://<api-base>/products?page=" + page, {
    headers: { "X-Api-Key": "vbk_your_key" },
  });
  if (res.status === 429) {
    // Structured contract: honor Retry-After, never screen-scrape.
    const wait = Number(res.headers.get("Retry-After")) * 1000;
    await new Promise((done) => setTimeout(done, wait));
    return listProducts(page);
  }
  if (!res.ok) throw new Error("products:read failed with " + res.status);
  return res.json();
}

Python

import requests

def list_products(page=1):
    res = requests.get(
        "https://<api-base>/products",
        params={"page": page},
        headers={"X-Api-Key": "vbk_your_key"},
        timeout=10,
    )
    res.raise_for_status()
    return res.json()

La v1 est en lecture seule par design : products:read, orders:read, customers:read et webhooks:read sont les seuls scopes qui existent. Des scopes d’écriture seraient une décision v1.x explicitement documentée — rien n’est prévu en silence.