Vai al contenuto

Docs: API REST e MCP

Il riferimento per i negozi che integrano PackMate nei propri flussi: OpenAPI 3.1, autenticazione, limiti per piano, codici di errore, webhook.

Indirizzo base
https://api.packmate.shop/api/v1
Apri il file OpenAPIConfigura MCP

Avvio rapido

Dall'installazione alla prima richiesta. La stessa chiave funziona per REST e MCP.

  1. Installa PackMate su Shopify

    Dopo l'approvazione nell'App Store: clicca su «Installa». PackMate funziona su ogni piano, puoi iniziare in Free.

  2. Genera chiave API

    Nell'app, sotto «Settings → AI access». Le chiavi iniziano con pm_live_ o, per la sandbox, con pm_test_.

    pm_live_4f3a8b9c2d1e...
    Esempio
  3. Prima richiesta

    Con curl, fetch o un altro client HTTP. L'header X-API-Key autentica ogni richiesta.

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

    La stessa chiave funziona per il server MCP. Come collegare la tua app di IA è spiegato sotto «Collegamento IA».

Autenticazione con chiave API

PackMate usa chiavi API con l'header X-API-Key. Le chiavi sono salvate con hash SHA-256, valgono per un solo negozio e si rinnovano in un click.

TemaCosa valeCome appare
Formato chiaveDue prefissi: pm_live_ per la produzione, pm_test_ per la sandbox. Seguono 48 caratteri esadecimali; il prefisso è in chiaro per riconoscere la chiave a colpo d'occhio.
pm_live_4f3a8b9c2d1e7f6a5b4c3d2e1f0a9b8c4f3a8b9c2d1e7f6a
Esempio
Formato headerInvia la chiave nell'header X-API-Key a ogni richiesta. Un Bearer in Authorization non è accettato.
X-API-Key: pm_live_…
RotazioneGenera una nuova chiave nell'app, sostituiscila nel client e poi revoca la vecchia. Fino a 10 chiavi attive per negozio per un passaggio graduale.
DELETE /api/v1/keys/:key_id
Response: 204 No Content
Permessi (scope)Ogni chiave ha dei permessi (scope). Chiavi nuove: lesen (lettura) oppure lesen + schreiben (scrittura); le chiavi più vecchie possono avere anche irreversibel. Creando la chiave nell’app scegli lo scopo; i permessi ne derivano. I permessi staff Shopify limitano inoltre chi genera chiavi.
scope: lesen | schreiben | irreversibel

Limiti per piano

Limiti per minuto e per picchi brevi (burst). I picchi sono smussati da un token bucket, le punte brevi non vengono bloccate. I piani Custom concordano limiti propri.

PianoRichieste al minutoBreve termine (burst)Contemporanee
Free601205
Basic12024010
Pro30060025
Business600120050
Custom2000concordatoconcordato

Al limite ottieni una risposta 429 con l'header Retry-After. L'header indica quanti secondi attendere.

Codici di errore

Semantica HTTP standard con corpi di errore PackMate. Ogni errore include un campo code leggibile dalle macchine e un messaggio leggibile.

CodiceLatoSignificatoCosa fai
400ClientBad request — corpo o query malformatoVerifica la forma della richiesta rispetto al file OpenAPI.
401ClientNon autorizzato — chiave API mancante o invalidaInvia l'header X-API-Key con una chiave pm_live_ o pm_test_ valida.
402ClientPagamento richiesto — limite del piano raggiuntoCambia piano o aspetta il prossimo ciclo. Usa «Recupera» (bulk reconciliation) dopo il cambio.
403ClientVietato — accesso negatoVerifica che il negozio sia abilitato, che la chiave abbia il permesso necessario e che non ci sia un blocco IA (richieste di scrittura dell'IA: KI_BESTAETIGUNG_FEHLT). query_carrier_rates oggi non recupera tariffe in tempo reale. Le etichette DHL non si possono creare tramite l’API (DHL_LABEL_API_GESPERRT; le chiavi senza il permesso irreversibel ricevono prima insufficient_scope); le crei in PackMate.
404ClientNon trovato — risorsa inesistenteVerifica l'ID. L'ordine potrebbe non essere ancora sincronizzato.
422ClientNon processabile — validazione semantica fallitaLeggi error.message — tipicamente dimensioni mancanti o materiale non valido.
429ClientTroppe richieste — limite raggiuntoAttendi secondo l'header Retry-After. Vedi la tabella «Limiti per piano» sopra.
500ServerErrore interno — bug dalla nostra parteRiprova una volta, poi scrivi a support@packmate.shop con il request_id del corpo dell'errore.
503ServerServizio non disponibile — manutenzione o problema al databaseRiprova con backoff esponenziale.

Webhook

PackMate registra webhook Shopify: quelli obbligatori GDPR e altri operativi. Shopify li firma tutti con HMAC-SHA256; PackMate verifica la firma prima dell'elaborazione.

TemaTipoCosa fa PackMate
customers/redactRichiestoIn caso di richiesta di cancellazione, PackMate sostituisce nome e indirizzo sulle etichette di spedizione degli ordini con «[redacted]», rimuove il link al PDF dell’etichetta e cancella l’e-mail salvata da precedenti richieste di accesso. I calcoli di imballaggio non contengono dati dei clienti e restano invariati.
customers/data_requestRichiestoUn cliente richiede l'esportazione dei suoi dati. PackMate la compila entro 30 giorni.
shop/redactRichiestoShopify lo invia circa 48 ore dopo la disinstallazione. PackMate elimina quindi tutti i dati del negozio dal proprio database.
app/uninstalledRichiestoL'app è stata disinstallata. PackMate contrassegna il negozio come disinstallato, revoca le sue chiavi API e termina l'abbonamento. I dati vengono eliminati con shop/redact.
products/updateOpzionaleProdotto modificato — PackMate aggiorna dimensioni e metafields in cache.
app/scopes_updateOpzionaleScope obbligatori modificati — PackMate registra la modifica.

Shopify firma tutti i webhook con HMAC-SHA256. PackMate verifica la firma prima dell'elaborazione.

Pronto? Genera una chiave API nell'app, sotto «Settings → AI access». La stessa chiave funziona per REST e MCP.