Snelstart
Van installatie tot je eerste request. Dezelfde sleutel werkt voor REST en MCP.
Installeer PackMate op Shopify
Na goedkeuring in de App Store: klik op «Installeren». PackMate werkt op elk plan, je kunt starten in Free.
API-sleutel genereren
In de app onder «Settings → AI access». Sleutels beginnen met pm_live_ of, voor de sandbox, met pm_test_.
Voorbeeldpm_live_4f3a8b9c2d1e...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_…'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.
| Onderwerp | Wat geldt | Zo ziet het eruit |
|---|---|---|
| Sleutelformaat | Twee 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. | |
| Headerformaat | Stuur de sleutel bij elke request in de header X-API-Key. Een Bearer in Authorization wordt niet geaccepteerd. | |
| Vernieuwen | Genereer 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. | |
| 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. | |
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.
| Plan | Requests per minuut | Kortstondig (burst) | Gelijktijdig |
|---|---|---|---|
| Free | 60 | 120 | 5 |
| Basic | 120 | 240 | 10 |
| Pro | 300 | 600 | 25 |
| Business | 600 | 1200 | 50 |
| Custom | 2000 | afgesproken | afgesproken |
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.
| Code | Kant | Betekenis | Wat je doet |
|---|---|---|---|
| 400 | Client | Bad request — body of query is onjuist | Controleer de vorm van de request tegen het OpenAPI-bestand. |
| 401 | Client | Niet geautoriseerd — API-sleutel ontbreekt of is ongeldig | Stuur de header X-API-Key met een geldige pm_live_- of pm_test_-sleutel. |
| 402 | Client | Betaling vereist — limiet van het plan bereikt | Wissel van plan of wacht op de volgende cyclus. Gebruik «Bijwerken» (bulk reconciliation) na de wissel. |
| 403 | Client | Verboden — toegang geweigerd | Controleer 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. |
| 404 | Client | Niet gevonden — bron bestaat niet | Controleer de ID. De bestelling is mogelijk nog niet gesynchroniseerd. |
| 422 | Client | Onverwerkbaar — semantische validatie mislukt | Lees error.message — meestal ontbrekende afmetingen of ongeldig materiaal. |
| 429 | Client | Te veel requests — limiet bereikt | Wacht zolang de header Retry-After aangeeft. Zie de tabel «Limieten per plan» hierboven. |
| 500 | Server | Interne fout — bug aan onze kant | Probeer één keer opnieuw, mail dan support@packmate.shop met de request_id uit de foutinhoud. |
| 503 | Server | Service niet beschikbaar — onderhoud of databaseprobleem | Probeer 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.
| Onderwerp | Soort | Wat PackMate doet |
|---|---|---|
| customers/redact | Verplicht | Bij 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_request | Verplicht | Een klant vraagt een export van zijn gegevens. PackMate stelt de export binnen 30 dagen samen. |
| shop/redact | Verplicht | Shopify stuurt dit ongeveer 48 uur na het verwijderen. PackMate wist dan alle gegevens van de winkel uit zijn database. |
| app/uninstalled | Verplicht | De 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/update | Optioneel | Product gewijzigd — PackMate ververst gecachte afmetingen en metafields. |
| app/scopes_update | Optioneel | Verplichte 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.