Zum Inhalt springen

Doku: REST-API und MCP

Die Referenz für Shops, die PackMate in eigene Abläufe einbinden: OpenAPI 3.1, Anmeldung, Grenzen je Tarif, Fehlercodes, Webhooks.

Basis-Adresse
https://api.packmate.shop/api/v1
OpenAPI-Datei öffnenMCP einrichten

Schnellstart

Von der Installation bis zur ersten Anfrage. Derselbe Schlüssel gilt für REST und MCP.

  1. PackMate in Shopify installieren

    Nach der Freigabe im App Store auf „Installieren“ klicken. PackMate läuft in jedem Tarif, du kannst mit Free anfangen.

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

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

ThemaWas giltSo sieht es aus
SchlüsselformatZwei 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.
pm_live_4f3a8b9c2d1e7f6a5b4c3d2e1f0a9b8c4f3a8b9c2d1e7f6a
Beispiel
Header-FormatSende den Schlüssel bei jeder Anfrage im Header X-API-Key. Ein Bearer-Token im Header Authorization wird nicht akzeptiert.
X-API-Key: pm_live_…
ErneuernErzeuge 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.
DELETE /api/v1/keys/:key_id
Response: 204 No Content
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.
scope: lesen | schreiben | irreversibel

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.

TarifAnfragen je MinuteKurzzeitig (Burst)Gleichzeitig
Free601205
Basic12024010
Pro30060025
Business600120050
Custom2000vereinbartvereinbart

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

CodeSeiteBedeutungWas du tust
400ClientBad Request — Body oder Query ist fehlerhaftPrüf die Form der Anfrage gegen die OpenAPI-Datei.
401ClientUnauthorized — fehlender oder ungültiger API-SchlüsselSende den Header X-API-Key mit einem gültigen pm_live_- oder pm_test_-Schlüssel.
402ClientPayment Required — Grenze des Tarifs erreichtWechsle den Tarif oder warte bis zum nächsten Abrechnungszyklus. Nutz „Nachpflegen“ nach dem Wechsel.
403ClientForbidden — Zugriff verweigertPrü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.
404ClientNot Found — Ressource existiert nichtPrüf die ID. Bei Bestellungen: Die Bestellung ist evtl. noch nicht synchronisiert.
422ClientUnprocessable — inhaltliche Prüfung fehlgeschlagenLies error.message — typischerweise fehlende Maße oder ungültiges Material.
429ClientToo Many Requests — Grenze je Tarif erreichtWarte so lange, wie der Header Retry-After angibt. Siehe die Tabelle „Grenzen je Tarif“ oben.
500ServerInternal Error — Fehler auf unserer SeiteWiederhole einmal, dann schreib an support@packmate.shop mit der request_id aus dem Fehlerinhalt.
503ServerService Unavailable — Wartung oder DatenbankproblemWiederhole 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.

ThemaArtWas PackMate tut
customers/redactPflichtBei 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_requestPflichtEin Kunde hat einen Datenexport beantragt. PackMate stellt den Export binnen 30 Tagen zusammen.
shop/redactPflichtShopify schickt das rund 48 Stunden nach der Deinstallation. PackMate löscht dann alle Daten des Shops aus seiner Datenbank.
app/uninstalledPflichtDie 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/updateOptionalEin Produkt hat sich geändert — PackMate aktualisiert zwischengespeicherte Maße und Metafields.
app/scopes_updateOptionalDie 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.