Schnellstart
Von der Installation bis zur ersten Anfrage. Derselbe Schlüssel gilt für REST und MCP.
PackMate in Shopify installieren
Nach der Freigabe im App Store auf „Installieren“ klicken. PackMate läuft in jedem Tarif, du kannst mit Free anfangen.
API-Schlüssel erzeugen
In der App unter „Einstellungen → KI-Zugriff“. Schlüssel beginnen mit pm_live_ oder, für die Sandbox, mit pm_test_.
Beispielpm_live_4f3a8b9c2d1e...Erste Anfrage stellen
Mit curl, fetch oder einem anderen HTTP-Client. Der Header X-API-Key meldet jede Anfrage an.
curl https://api.packmate.shop/api/v1/health \ -H 'X-API-Key: pm_live_…'Danach: MCP verbinden
Derselbe Schlüssel gilt für den MCP-Server. Wie du dein KI-Programm verbindest, steht unter „KI-Anbindung“.
Anmeldung mit API-Schlüssel
PackMate nutzt API-Schlüssel mit dem Header X-API-Key. Schlüssel werden mit SHA-256 gehasht gespeichert, gelten für genau einen Shop und lassen sich in einem Klick erneuern.
| Thema | Was gilt | So sieht es aus |
|---|---|---|
| Schlüsselformat | Zwei Präfixe: pm_live_ für den Betrieb, pm_test_ für die Sandbox. Danach folgen 48 Hex-Zeichen; das Präfix steht im Klartext, damit man den Schlüssel auf einen Blick erkennt. | |
| Header-Format | Sende den Schlüssel bei jeder Anfrage im Header X-API-Key. Ein Bearer-Token im Header Authorization wird nicht akzeptiert. | |
| Erneuern | Erzeuge in der App einen neuen Schlüssel, tausche ihn im Client und widerrufe dann den alten. PackMate erlaubt bis zu 10 aktive Schlüssel je Shop, damit der Wechsel gestaffelt laufen kann. | |
| Rechte (Scopes) | Jeder Schlüssel trägt Rechte (Scopes). Neue Schlüssel: lesen oder lesen + schreiben; ältere Schlüssel können zusätzlich irreversibel tragen. Beim Anlegen in der App wählst du den Zweck, die Rechte folgen daraus. Zusätzlich begrenzen die Shopify-Mitarbeiterrechte, wer Schlüssel erzeugen darf. | |
Grenzen je Tarif
Grenzen je Minute und für kurze Spitzen (Burst). Spitzen werden über einen Token-Bucket geglättet, kurze Ausschläge werden nicht geblockt. Für Custom-Tarife werden eigene Grenzen vereinbart.
| Tarif | Anfragen je Minute | Kurzzeitig (Burst) | Gleichzeitig |
|---|---|---|---|
| Free | 60 | 120 | 5 |
| Basic | 120 | 240 | 10 |
| Pro | 300 | 600 | 25 |
| Business | 600 | 1200 | 50 |
| Custom | 2000 | vereinbart | vereinbart |
Wenn du die Grenze erreichst, bekommst du eine 429-Antwort mit dem Header Retry-After. Der Header sagt dir, wie viele Sekunden zu warten sind.
Fehlercodes
Standard-HTTP-Semantik mit PackMate-eigenen Fehlerinhalten. Jeder Fehler enthält ein maschinenlesbares Feld code und eine lesbare Meldung (message).
| Code | Seite | Bedeutung | Was du tust |
|---|---|---|---|
| 400 | Client | Bad Request — Body oder Query ist fehlerhaft | Prüf die Form der Anfrage gegen die OpenAPI-Datei. |
| 401 | Client | Unauthorized — fehlender oder ungültiger API-Schlüssel | Sende den Header X-API-Key mit einem gültigen pm_live_- oder pm_test_-Schlüssel. |
| 402 | Client | Payment Required — Grenze des Tarifs erreicht | Wechsle den Tarif oder warte bis zum nächsten Abrechnungszyklus. Nutz „Nachpflegen“ nach dem Wechsel. |
| 403 | Client | Forbidden — Zugriff verweigert | Prüf, ob der Laden freigeschaltet ist, der Schlüssel das nötige Recht hat und ob eine KI-Sperre greift (schreibende KI-Anfragen: KI_BESTAETIGUNG_FEHLT). query_carrier_rates ruft heute keine Live-Preise ab. DHL-Etiketten lassen sich über die Schnittstelle nicht erstellen (DHL_LABEL_API_GESPERRT, bei Schlüsseln ohne das Recht irreversibel schon vorher insufficient_scope); du erstellst sie in PackMate. |
| 404 | Client | Not Found — Ressource existiert nicht | Prüf die ID. Bei Bestellungen: Die Bestellung ist evtl. noch nicht synchronisiert. |
| 422 | Client | Unprocessable — inhaltliche Prüfung fehlgeschlagen | Lies error.message — typischerweise fehlende Maße oder ungültiges Material. |
| 429 | Client | Too Many Requests — Grenze je Tarif erreicht | Warte so lange, wie der Header Retry-After angibt. Siehe die Tabelle „Grenzen je Tarif“ oben. |
| 500 | Server | Internal Error — Fehler auf unserer Seite | Wiederhole einmal, dann schreib an support@packmate.shop mit der request_id aus dem Fehlerinhalt. |
| 503 | Server | Service Unavailable — Wartung oder Datenbankproblem | Wiederhole mit wachsendem Abstand (Exponential Backoff). |
Webhooks
PackMate registriert Shopify-Webhooks: die DSGVO-Pflicht-Webhooks und weitere für den Betrieb. Shopify signiert alle Payloads mit HMAC-SHA256; PackMate prüft die Signatur vor der Verarbeitung.
| Thema | Art | Was PackMate tut |
|---|---|---|
| customers/redact | Pflicht | Bei einer Löschanfrage ersetzt PackMate Name und Adresse auf den Versandlabels der Bestellungen durch ‚[redacted]‘, entfernt den Link zum Label-PDF und löscht die gespeicherte E-Mail aus früheren Auskunftsanfragen. Die Packberechnungen enthalten keine Kundendaten und bleiben unverändert. |
| customers/data_request | Pflicht | Ein Kunde hat einen Datenexport beantragt. PackMate stellt den Export binnen 30 Tagen zusammen. |
| shop/redact | Pflicht | Shopify schickt das rund 48 Stunden nach der Deinstallation. PackMate löscht dann alle Daten des Shops aus seiner Datenbank. |
| app/uninstalled | Pflicht | Die App wurde deinstalliert. PackMate markiert den Shop als deinstalliert, widerruft seine API-Schlüssel und beendet das Abo. Gelöscht werden die Daten mit shop/redact. |
| products/update | Optional | Ein Produkt hat sich geändert — PackMate aktualisiert zwischengespeicherte Maße und Metafields. |
| app/scopes_update | Optional | Die Pflicht-Scopes haben sich geändert — PackMate protokolliert die Änderung. |
Shopify signiert alle Webhooks mit HMAC-SHA256. PackMate prüft die Signatur vor der Verarbeitung.
Bereit? Erzeug einen API-Schlüssel in der App unter „Einstellungen → KI-Zugriff“. Derselbe Schlüssel gilt für REST und MCP.