Aller au contenu

Docs : API REST et MCP

La référence pour les boutiques qui intègrent PackMate à leurs propres flux : OpenAPI 3.1, authentification, limites par plan, codes d'erreur, webhooks.

Adresse de base
https://api.packmate.shop/api/v1
Ouvrir le fichier OpenAPIConfigurer MCP

Démarrage rapide

De l'installation à la première requête. La même clé fonctionne pour REST et MCP.

  1. 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.

  2. 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_.

    pm_live_4f3a8b9c2d1e...
    Exemple
  3. 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_…'
  4. 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.

SujetCe 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.
pm_live_4f3a8b9c2d1e7f6a5b4c3d2e1f0a9b8c4f3a8b9c2d1e7f6a
Exemple
Format du headerEnvoyez la clé dans le header X-API-Key à chaque requête. Un Bearer dans Authorization n'est pas accepté.
X-API-Key: pm_live_…
RotationGé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.
DELETE /api/v1/keys/:key_id
Response: 204 No Content
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.
scope: lesen | schreiben | irreversibel

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.

PlanRequêtes par minuteCourt terme (burst)Simultanées
Free601205
Basic12024010
Pro30060025
Business600120050
Custom2000convenuconvenu

À 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.

CodeCôtéSignificationCe que vous faites
400ClientBad request — corps ou query mal forméVérifiez la forme de la requête contre le fichier OpenAPI.
401ClientNon autorisé — clé API manquante ou invalideEnvoyez le header X-API-Key avec une clé pm_live_ ou pm_test_ valide.
402ClientPaiement requis — plafond du plan atteintChangez de plan ou attendez le prochain cycle. Utilisez « Rattraper » (bulk reconciliation) après le changement.
403ClientInterdit — 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.
404ClientNon trouvé — ressource inexistanteVérifiez l'ID. Pour les commandes, peut-être pas encore synchronisée.
422ClientNon traitable — validation sémantique échouéeLisez error.message — typiquement dimensions manquantes ou matériau invalide.
429ClientTrop de requêtes — limite atteintePatientez selon le header Retry-After. Voir le tableau « Limites par plan » ci-dessus.
500ServeurErreur interne — bug de notre côtéRéessayez une fois, puis écrivez à support@packmate.shop avec le request_id du corps d'erreur.
503ServeurService indisponible — maintenance ou souci de base de donnéesRé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.

SujetTypeCe que fait PackMate
customers/redactRequisEn 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_requestRequisUn client demande un export de ses données. PackMate compile l'export sous 30 jours.
shop/redactRequisShopify 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/uninstalledRequisL'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/updateOptionnelProduit modifié — PackMate rafraîchit les dimensions et metafields en cache.
app/scopes_updateOptionnelScopes 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.