Naar inhoud springen

Docs: REST-API en MCP

De referentie voor winkels die PackMate in eigen processen inbouwen: OpenAPI 3.1, aanmelden, limieten per plan, foutcodes, webhooks.

Basisadres
https://api.packmate.shop/api/v1
OpenAPI-bestand openenMCP instellen

Snelstart

Van installatie tot je eerste request. Dezelfde sleutel werkt voor REST en MCP.

  1. Installeer PackMate op Shopify

    Na goedkeuring in de App Store: klik op «Installeren». PackMate werkt op elk plan, je kunt starten in Free.

  2. API-sleutel genereren

    In de app onder «Settings → AI access». Sleutels beginnen met pm_live_ of, voor de sandbox, met pm_test_.

    pm_live_4f3a8b9c2d1e...
    Voorbeeld
  3. Eerste request

    Met curl, fetch of een andere HTTP-client. De header X-API-Key meldt elke request aan.

    curl https://api.packmate.shop/api/v1/health \
      -H 'X-API-Key: pm_live_…'
  4. Daarna: MCP koppelen

    Dezelfde sleutel werkt voor de MCP-server. Hoe je je AI-app koppelt, staat onder «AI-koppeling».

Aanmelden met API-sleutel

PackMate gebruikt API-sleutels met de header X-API-Key. Sleutels worden met SHA-256 gehasht opgeslagen, gelden voor precies één winkel en zijn met één klik te vernieuwen.

OnderwerpWat geldtZo ziet het eruit
SleutelformaatTwee prefixes: pm_live_ voor productie, pm_test_ voor de sandbox. Daarna volgen 48 hex-tekens; de prefix staat in platte tekst, zodat je een sleutel in één oogopslag herkent.
pm_live_4f3a8b9c2d1e7f6a5b4c3d2e1f0a9b8c4f3a8b9c2d1e7f6a
Voorbeeld
HeaderformaatStuur de sleutel bij elke request in de header X-API-Key. Een Bearer in Authorization wordt niet geaccepteerd.
X-API-Key: pm_live_…
VernieuwenGenereer in de app een nieuwe sleutel, wissel hem in je client en trek dan de oude in. Tot 10 actieve sleutels per winkel voor een gefaseerde overgang.
DELETE /api/v1/keys/:key_id
Response: 204 No Content
Rechten (scopes)Elke sleutel heeft rechten (scopes). Nieuwe sleutels: lesen (lezen) of lesen + schreiben (schrijven); oudere sleutels kunnen daarnaast irreversibel hebben. Bij het aanmaken in de app kies je het doel; de rechten volgen daaruit. Shopify-staffrechten beperken bovendien wie sleutels genereert.
scope: lesen | schreiben | irreversibel

Limieten per plan

Limieten per minuut en voor korte pieken (burst). Pieken worden gladgestreken met een token bucket, korte uitschieters worden niet geblokkeerd. Voor Custom-plannen worden eigen limieten afgesproken.

PlanRequests per minuutKortstondig (burst)Gelijktijdig
Free601205
Basic12024010
Pro30060025
Business600120050
Custom2000afgesprokenafgesproken

Bij de limiet krijg je een 429-antwoord met de header Retry-After. De header geeft aan hoeveel seconden je moet wachten.

Foutcodes

Standaard HTTP-semantiek met PackMate-eigen foutinhoud. Elke fout bevat een machineleesbaar veld code en een leesbaar bericht.

CodeKantBetekenisWat je doet
400ClientBad request — body of query is onjuistControleer de vorm van de request tegen het OpenAPI-bestand.
401ClientNiet geautoriseerd — API-sleutel ontbreekt of is ongeldigStuur de header X-API-Key met een geldige pm_live_- of pm_test_-sleutel.
402ClientBetaling vereist — limiet van het plan bereiktWissel van plan of wacht op de volgende cyclus. Gebruik «Bijwerken» (bulk reconciliation) na de wissel.
403ClientVerboden — toegang geweigerdControleer of de winkel is vrijgeschakeld, de sleutel het vereiste recht heeft en of een AI-blokkade geldt (schrijvende AI-verzoeken: KI_BESTAETIGUNG_FEHLT). query_carrier_rates haalt vandaag geen live tarieven op. DHL-labels kun je niet via de API aanmaken (DHL_LABEL_API_GESPERRT; sleutels zonder het recht irreversibel krijgen eerst insufficient_scope); je maakt ze aan in PackMate.
404ClientNiet gevonden — bron bestaat nietControleer de ID. De bestelling is mogelijk nog niet gesynchroniseerd.
422ClientOnverwerkbaar — semantische validatie misluktLees error.message — meestal ontbrekende afmetingen of ongeldig materiaal.
429ClientTe veel requests — limiet bereiktWacht zolang de header Retry-After aangeeft. Zie de tabel «Limieten per plan» hierboven.
500ServerInterne fout — bug aan onze kantProbeer één keer opnieuw, mail dan support@packmate.shop met de request_id uit de foutinhoud.
503ServerService niet beschikbaar — onderhoud of databaseprobleemProbeer opnieuw met exponentiële backoff.

Webhooks

PackMate registreert Shopify-webhooks: de verplichte AVG-webhooks en operationele. Shopify ondertekent alle payloads met HMAC-SHA256; PackMate controleert de handtekening vóór de verwerking.

OnderwerpSoortWat PackMate doet
customers/redactVerplichtBij een verwijderverzoek vervangt PackMate naam en adres op de verzendlabels van de bestellingen door “[redacted]”, verwijdert de link naar de label-pdf en wist het opgeslagen e-mailadres uit eerdere inzageverzoeken. Inpakberekeningen bevatten geen klantgegevens en blijven ongewijzigd.
customers/data_requestVerplichtEen klant vraagt een export van zijn gegevens. PackMate stelt de export binnen 30 dagen samen.
shop/redactVerplichtShopify stuurt dit ongeveer 48 uur na het verwijderen. PackMate wist dan alle gegevens van de winkel uit zijn database.
app/uninstalledVerplichtDe app is verwijderd. PackMate markeert de winkel als verwijderd, trekt de API-sleutels in en beëindigt het abonnement. De gegevens worden gewist met shop/redact.
products/updateOptioneelProduct gewijzigd — PackMate ververst gecachte afmetingen en metafields.
app/scopes_updateOptioneelVerplichte scopes gewijzigd — PackMate registreert de wijziging.

Shopify ondertekent alle webhooks met HMAC-SHA256. PackMate controleert de handtekening vóór de verwerking.

Klaar? Genereer een API-sleutel in de app onder «Settings → AI access». Dezelfde sleutel werkt voor REST en MCP.