Documentation API annuaire-shopify

En bref

• Base URL : https://api.annuaire-shopify.fr/v1
• Authentification : jeton Bearer dans l’en-tête Authorization
• Format : JSON REST classique, pas de GraphQL
• Pagination : curseur opaque (cursor / next_cursor)
• Limites de débit : 50 000 appels / mois, 20 requêtes / seconde
• Notifications automatiques : POST signés HMAC-SHA256, 5 actifs maximum
• Spécification : OpenAPI 3.1 disponible au téléchargement (lien à brancher côté dev)
• Format requis : Pro avec API 199 €/mois — voir tarifs

Pour le guide narratif et les patterns d’intégration côté code, voir le guide API annuaire Shopify qui complète cette référence.

Authentification

Toutes les requêtes nécessitent un jeton Bearer dans l’en-tête Authorization. Le jeton est généré dans le tableau de bord et porte les droits de votre compte.

GET /v1/stores HTTP/1.1
Host: api.annuaire-shopify.fr
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxx
Accept: application/json

Gestion des clés

• Plusieurs clés actives par compte (utile pour la rotation sans interruption).
• Une clé par environnement recommandée (staging, production).
• Révocation immédiate depuis le tableau de bord.
• Stockage : jamais commit. Variable d’environnement en dev, gestionnaire de secrets en production (AWS Secrets Manager, GCP Secret Manager, Vault, Doppler).

Codes d’erreur d’authentification

Endpoint principal : /v1/stores

Liste les boutiques Shopify de la base. C’est l’endpoint que vous utiliserez à 90 %.

Méthode

GET /v1/stores

Paramètres de requête

Roadmap — les filtres techno secondaires (klaviyo, shopify_plus, judge_me, recharge, yotpo) ne sont pas encore disponibles. Ils seront ajoutés au fur et à mesure des étapes 1 et 2 de la roadmap publique, sans casser la signature existante de l’endpoint.

Réponse

{
  "data": [
    {
      "id": "str_a8f3c2",
      "domain": "exemple-marchand.fr",
      "store_name": "Exemple Marchand",
      "tld": "fr",
      "theme": "Prestige",
      "theme_version": "9.4.0",
      "first_seen": "2024-08-12",
      "last_verified": "2026-04-22"
    }
  ],
  "next_cursor": "eyJpZCI6InN0cl9hOGYzYzIifQ==",
  "remaining_quota": 49823
}

Le champ remaining_quota est renvoyé sur chaque réponse 2xx pour faciliter la surveillance côté client.

Exemple curl

Liste 100 marchands sur extension .fr avec thème Prestige :

curl -H "Authorization: Bearer $API_KEY" \
  "https://api.annuaire-shopify.fr/v1/stores?tld=fr&theme=Prestige&limit=100"

Codes de réponse

Endpoint domaine unique : /v1/stores/{domain}

Récupère une fiche par domaine canonique. Utile pour l’enrichissement CRM unitaire (« est-ce que ce compte tourne sous Shopify ? »).

Méthode

GET /v1/stores/exemple-marchand.fr

Réponse

{
  "id": "str_a8f3c2",
  "domain": "exemple-marchand.fr",
  "store_name": "Exemple Marchand",
  "tld": "fr",
  "theme": "Prestige",
  "theme_version": "9.4.0",
  "first_seen": "2024-08-12",
  "last_verified": "2026-04-22"
}

Codes de réponse spécifiques

Pagination par curseur

L’API utilise un curseur opaque, pas un décalage numérique. C’est volontaire : sur une base qui change pendant l’itération, un décalage saute ou duplique des lignes.

Pattern d’utilisation

1. Première requête sans cursor.
2. La réponse contient next_cursor (ou null si dernière page).
3. Passer ce curseur dans la requête suivante.
4. Continuer jusqu’à next_cursor: null.

Précisions

• Ne décodez jamais le curseur. Format interne, susceptible de changer.
• Ne stockez pas les curseurs entre deux runs. Pour reprendre une synchronisation incrémentale, utilisez updated_since avec un timestamp.
• Le curseur peut être invalidé si la base est ré-indexée. Dans ce cas, l’API renvoie 400 cursor_expired et vous relancez depuis le début.

Notifications automatiques (webhooks)

Plutôt que d’interroger l’endpoint en boucle, vous pouvez recevoir des notifications push sur les événements qui correspondent à vos filtres.

Configuration

Dans le tableau de bord :

1. Onglet « Notifications automatiques ».
2. Ajouter un point de réception (URL HTTPS).
3. Filtres optionnels (par extension, par thème, par événement).
4. Générer le secret HMAC partagé.

Quota : 5 notifications automatiques actives par compte sur le format Pro avec API.

Événements supportés

Charge utile

{
  "event": "store.detected",
  "id": "evt_2x9f3a",
  "timestamp": "2026-04-27T08:14:22Z",
  "data": {
    "id": "str_b7d4e1",
    "domain": "nouveau-marchand.fr",
    "store_name": "Nouveau Marchand",
    "tld": "fr",
    "theme": "Dawn",
    "first_seen": "2026-04-27"
  }
}

Vérification de signature HMAC-SHA256

Chaque POST inclut un en-tête X-Annuaire-Signature calculé en HMAC-SHA256 sur le corps brut, encodé hexadécimal.

import hmac
import hashlib

def verify(body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Deux pièges à éviter :

• Calculer la signature sur le corps brut, pas sur un JSON re-sérialisé.
• Utiliser compare_digest (temps constant), pas ==. Sinon vous exposez un oracle temporel.

Politique de nouvelle tentative

Si votre point de réception renvoie un statut non-2xx ou met plus de 10 secondes à répondre, l’annuaire retente avec un délai exponentiel : 1 min, 5 min, 30 min, 2 h, 8 h. Au-delà de 5 échecs consécutifs, la notification automatique passe en paused et une alerte email est envoyée. Réactivation manuelle depuis le tableau de bord.

Idempotence

Chaque événement a un id unique (evt_*). Indexez vos événements reçus sur ce champ avec un INSERT ... ON CONFLICT DO NOTHING pour éviter les doublons sur nouvelle tentative.

Limites de débit

Sur le format Pro avec API à 199 €/mois :

• 50 000 appels API / mois sur l’ensemble des endpoints.
• 20 requêtes / seconde en pic court (token bucket).
• 5 notifications automatiques actives simultanées.
• 3 sièges utilisateur sur le tableau de bord.
• 20 000 boutiques accessibles / mois dans les listings.

Comportement au dépassement

Pas de débit silencieux, pas de surfacturation cachée.

Surveillance côté client

Chaque réponse 2xx inclut deux en-têtes :

X-Quota-Remaining: 49823
X-Rate-Limit-Remaining: 18

Permet de monitorer la consommation et d’ajuster votre cadence.

Idempotence sur écritures

Pour les futurs endpoints en POST/PATCH (gestion de listes personnalisées, étiquettes), l’API supporte un en-tête Idempotency-Key.

POST /v1/lists HTTP/1.1
Authorization: Bearer $API_KEY
Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7
Content-Type: application/json

{
  "name": "Ma liste",
  "filters": {"tld": "fr"}
}

Vous générez un UUID v4 par opération métier. L’API garantit qu’une nouvelle tentative avec la même clé dans les 24 heures ne ré-applique pas l’opération.

Spécification OpenAPI

La spec complète au format OpenAPI 3.1 est disponible au téléchargement (lien à brancher côté dev : https://api.annuaire-shopify.fr/v1/openapi.json).

Compatible avec :

• openapi-typescript pour générer les types TypeScript.
• datamodel-code-generator pour les modèles Pydantic.
• Swagger UI / Redoc pour la documentation interactive auto-générée.

Statut de la roadmap

Voici ce qui est disponible aujourd’hui et ce qui est sur la roadmap publique.

Disponible aujourd’hui

• Endpoint /v1/stores avec filtres tld, theme, theme_version, first_seen_after, updated_since, domain.
• Endpoint /v1/stores/{domain}.
• Pagination par curseur, surveillance des quotas via en-têtes.
• Notifications automatiques store.detected, store.updated, store.removed avec signature HMAC.

Sur la roadmap (sans date publique)

• Étape 1 : filtres shopify_plus et klaviyo (booléens). Notifications automatiques associées.
• Étape 2 : filtres recharge, yotpo, judge_me, markets (booléens).
• Étape 3 : filtre vertical (secteur). Notifications automatiques associées.
• Plus tard : endpoint MCP pour intégration directe Claude / autre agent IA.

Les ajouts se feront sans casser la signature existante des endpoints. Si vous itérez aujourd’hui sur les filtres disponibles, votre intégration restera fonctionnelle après livraison des étapes suivantes.

Limites assumées

Transparence sur ce qui n’est pas garanti à ce format tarifaire :

• Pas d’engagement de service contractuel sur le format Pro avec API à 199 €/mois. Disponibilité 99,5 % annoncée en meilleur effort, non opposable juridiquement. Pour un engagement de service avec pénalités, c’est un accord sur mesure.
• Géo-distribution mono-région. L’API est servie depuis AWS eu-west-3 (Paris). Latence P50 ~180 ms depuis l’Europe, ~250 ms depuis l’East Coast US, ~400 ms depuis APAC.
• Pas de SDK officiel. REST + JSON, n’importe quel client HTTP suffit. Un SDK Python communautaire est sur la liste, mais on stabilise la signature avant de geler une distribution.
• Pas de bac à sable séparé. Une seule URL api.annuaire-shopify.fr. Pour itérer en dev sans consommer le quota production, utilisez les filtres restrictifs (domain= sur un domaine connu, limit=1).

Démarrer

1. Souscrire à Pro avec API sur la page tarifs — 25 places ouvertes au lancement.
2. Générer un jeton dans le tableau de bord, onglet « Clés API ».
3. Tester avec curl : curl -H "Authorization: Bearer $API_KEY" "https://api.annuaire-shopify.fr/v1/stores?limit=10".
4. Configurer les notifications automatiques dans le tableau de bord si votre flux le nécessite.
5. Surveiller le quota via les en-têtes X-Quota-Remaining et X-Rate-Limit-Remaining.

Pour le guide narratif avec exemples Python / Node complets et calcul de seuil de rentabilité face à un outil maison, voir le guide API annuaire Shopify.

Support technique

• Email : voir la page contact.
• Documentation : cette page + guide API + cas d’usage développeurs d’outils Shopify.
• Temps de réponse : 1 jour ouvré sur Pro avec API. Délai plus court sur accord sur mesure.

← Retour à l’accueil · Voir tarifs · Guide API narratif · Cas d’usage développeurs · Roadmap publique