Démarrage rapide
De l'installation à la première requête. La même clé fonctionne pour REST et MCP.
Installer PackMate sur Shopify
Après la validation dans l'App Store : cliquez « Installer ». PackMate fonctionne sur tout plan, vous pouvez démarrer en Free.
Générer une clé API
Dans l'app, sous « Settings → AI access ». Les clés commencent par pm_live_ ou, pour la sandbox, par pm_test_.
Exemplepm_live_4f3a8b9c2d1e...Première requête
Avec curl, fetch ou un autre client HTTP. Le header X-API-Key authentifie chaque requête.
curl https://api.packmate.shop/api/v1/health \ -H 'X-API-Key: pm_live_…'Ensuite : connecter MCP
La même clé fonctionne pour le serveur MCP. La connexion de votre app d’IA est décrite sous « Connexion IA ».
Authentification par clé API
PackMate utilise des clés API avec le header X-API-Key. Les clés sont stockées hashées en SHA-256, valables pour une seule boutique, et renouvelables en un clic.
| Sujet | Ce qui s'applique | À quoi ça ressemble |
|---|---|---|
| Format de clé | Deux préfixes : pm_live_ pour la production, pm_test_ pour la sandbox. Suivent 48 caractères hexadécimaux ; le préfixe est en clair pour reconnaître la clé d'un coup d'œil. | |
| Format du header | Envoyez la clé dans le header X-API-Key à chaque requête. Un Bearer dans Authorization n'est pas accepté. | |
| Rotation | Générez une nouvelle clé dans l'app, échangez-la dans votre client, puis révoquez l'ancienne. Jusqu'à 10 clés actives par boutique pour une transition échelonnée. | |
| Droits (scopes) | Chaque clé porte des droits (scopes). Nouvelles clés : lesen (lecture) ou lesen + schreiben (écriture) ; les clés plus anciennes peuvent aussi porter irreversibel. En créant la clé dans l’app, vous choisissez sa finalité ; les droits en découlent. Les permissions staff Shopify limitent aussi qui peut générer des clés. | |
Limites par plan
Limites par minute et pour les pics brefs (burst). Les pics sont lissés par token bucket, les pointes courtes ne sont pas bloquées. Les plans Custom conviennent de limites propres.
| Plan | Requêtes par minute | Court terme (burst) | Simultanées |
|---|---|---|---|
| Free | 60 | 120 | 5 |
| Basic | 120 | 240 | 10 |
| Pro | 300 | 600 | 25 |
| Business | 600 | 1200 | 50 |
| Custom | 2000 | convenu | convenu |
À la limite, vous obtenez une réponse 429 avec le header Retry-After. Il indique combien de secondes attendre.
Codes d'erreur
Sémantique HTTP standard avec corps d'erreur PackMate. Chaque erreur inclut un champ code lisible par machine et un message lisible.
| Code | Côté | Signification | Ce que vous faites |
|---|---|---|---|
| 400 | Client | Bad request — corps ou query mal formé | Vérifiez la forme de la requête contre le fichier OpenAPI. |
| 401 | Client | Non autorisé — clé API manquante ou invalide | Envoyez le header X-API-Key avec une clé pm_live_ ou pm_test_ valide. |
| 402 | Client | Paiement requis — plafond du plan atteint | Changez de plan ou attendez le prochain cycle. Utilisez « Rattraper » (bulk reconciliation) après le changement. |
| 403 | Client | Interdit — accès refusé | Vérifiez que la boutique est activée, que la clé a le droit requis et qu'aucun blocage IA ne s'applique (requêtes IA en écriture : KI_BESTAETIGUNG_FEHLT). query_carrier_rates ne récupère pas de tarifs en direct aujourd’hui. Les étiquettes DHL ne peuvent pas être créées via l’API (DHL_LABEL_API_GESPERRT ; les clés sans le droit irreversibel reçoivent d’abord insufficient_scope) ; vous les créez dans PackMate. |
| 404 | Client | Non trouvé — ressource inexistante | Vérifiez l'ID. Pour les commandes, peut-être pas encore synchronisée. |
| 422 | Client | Non traitable — validation sémantique échouée | Lisez error.message — typiquement dimensions manquantes ou matériau invalide. |
| 429 | Client | Trop de requêtes — limite atteinte | Patientez selon le header Retry-After. Voir le tableau « Limites par plan » ci-dessus. |
| 500 | Serveur | Erreur interne — bug de notre côté | Réessayez une fois, puis écrivez à support@packmate.shop avec le request_id du corps d'erreur. |
| 503 | Serveur | Service indisponible — maintenance ou souci de base de données | Réessayez avec un backoff exponentiel. |
Webhooks
PackMate enregistre des webhooks Shopify : les webhooks RGPD obligatoires et d'autres opérationnels. Shopify les signe tous avec HMAC-SHA256 ; PackMate vérifie la signature avant le traitement.
| Sujet | Type | Ce que fait PackMate |
|---|---|---|
| customers/redact | Requis | En cas de demande de suppression, PackMate remplace le nom et l’adresse sur les étiquettes d’expédition des commandes par « [redacted] », retire le lien vers le PDF de l’étiquette et supprime l’e-mail enregistré lors de demandes d’accès antérieures. Les calculs d’emballage ne contiennent aucune donnée client et restent inchangés. |
| customers/data_request | Requis | Un client demande un export de ses données. PackMate compile l'export sous 30 jours. |
| shop/redact | Requis | Shopify l'envoie environ 48 heures après la désinstallation. PackMate supprime alors toutes les données de la boutique de sa base de données. |
| app/uninstalled | Requis | L'application a été désinstallée. PackMate marque la boutique comme désinstallée, révoque ses clés API et met fin à l'abonnement. Les données sont supprimées avec shop/redact. |
| products/update | Optionnel | Produit modifié — PackMate rafraîchit les dimensions et metafields en cache. |
| app/scopes_update | Optionnel | Scopes obligatoires modifiés — PackMate journalise le changement. |
Shopify signe tous les webhooks avec HMAC-SHA256. PackMate vérifie la signature avant le traitement.
Prêt ? Générez une clé API dans l'app, sous « Settings → AI access ». La même clé fonctionne pour REST et MCP.