DOC
Accueil/ Projets/ KOBIKE Tracking Notifier/ Guide 04 - API Shopify (récupérer l'email client par n° de commande)

Guide 04 - API Shopify (récupérer l'email client par n° de commande)

Objectif : quand l'email manque dans le Tencent Docs, retrouver l'email du client à partir du Platform order number (ex. KO260107-1) via l'API Admin Shopify. Voir ADR 0002.

Disponibilité de l'API - vérifié ✅

Shopify propose une API Admin ouverte à toute boutique. On crée une application personnalisée (custom app) directement dans l'admin de la boutique, sans validation Shopify, tant qu'elle reste installée sur cette boutique. 2 points d'attention importants :

  1. Donnée client protégée (email = PII). Lire l'email d'un client relève des Protected Customer Data. Il faut activer et configurer l'accès aux données client protégées pour l'app, sinon l'API renvoie une erreur du type « This app is not approved to access ... protected customer data ». Pour une custom app sur votre propre boutique, cela se fait en cochant les données/champs utilisés (pas de revue Shopify pour une app installée uniquement sur votre boutique). Pour une app publique/multi-boutiques, une approbation Shopify est requise.
  2. GraphQL, pas REST. Depuis le 1er avril 2025, les nouvelles apps doivent être bâties avec l'API GraphQL Admin (REST = legacy). Le guide privilégie donc GraphQL.

1. Créer la custom app

  1. Admin Shopify → Settings → Apps and sales channels → Develop apps.
  2. Create an app → nommer (ex. kobike-n8n-enrichment).
  3. Configuration → Admin API scopes : cocher au minimum
    • read_orders
    • read_customers
  4. Protected customer data : dans la configuration de l'app, déclarer l'usage des données client (email) et la finalité (envoi de notifications de suivi).
  5. Install app → récupérer l'Admin API access token (shpat_...). ⚠️ Affiché une seule fois : à stocker dans les credentials n8n.

2. Retrouver une commande par son nom (GraphQL)

Le Platform order number correspond au name de la commande Shopify (souvent préfixé #). Requête :

query FindOrder($q: String!) {
  orders(first: 1, query: $q) {
    edges {
      node {
        name
        email
        customer { email firstName lastName }
      }
    }
  }
}

Variables :

{ "q": "name:KO260107-1" }

Endpoint : POST https://<boutique>.myshopify.com/admin/api/2025-07/graphql.json En-têtes : X-Shopify-Access-Token: shpat_... + Content-Type: application/json.

L'email peut être sur node.email (email de contact de la commande) et/ou node.customer.email. Prendre le premier non vide.

3. Intégration n8n

  • Utiliser le nœud Shopify (si les scopes suffisent) ou un nœud HTTP Request vers l'endpoint GraphQL.
  • Ne déclencher l'appel Shopify que si l'email est absent en local (table client) - voir la cascade de l'ADR 0002.
  • En cas de succès, écrire l'email dans client pour éviter les appels répétés.

4. Limites & bonnes pratiques

  • Rate limiting : GraphQL utilise un système de coût (points). Espacer les appels ; l'approche « cache local d'abord » réduit fortement le volume.
  • Commandes physiques : les ventes en boutique (Shifter) ne sont pas dans Shopify → si non trouvée, passer à Shifter (guide 05).
  • Sécurité : stocker le token uniquement dans les credentials n8n, jamais en clair dans un workflow exporté.

Checklist

  • Custom app créée avec read_orders + read_customers.
  • Accès Protected Customer Data activé/configuré.
  • Token shpat_... stocké dans n8n.
  • Requête GraphQL name:... testée et renvoyant l'email.

Ressources