Avvio rapido
Dall'installazione alla prima richiesta. La stessa chiave funziona per REST e MCP.
Installa PackMate su Shopify
Dopo l'approvazione nell'App Store: clicca su «Installa». PackMate funziona su ogni piano, puoi iniziare in Free.
Genera chiave API
Nell'app, sotto «Settings → AI access». Le chiavi iniziano con pm_live_ o, per la sandbox, con pm_test_.
Esempiopm_live_4f3a8b9c2d1e...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_…'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.
| Tema | Cosa vale | Come appare |
|---|---|---|
| Formato chiave | Due 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. | |
| Formato header | Invia la chiave nell'header X-API-Key a ogni richiesta. Un Bearer in Authorization non è accettato. | |
| Rotazione | Genera una nuova chiave nell'app, sostituiscila nel client e poi revoca la vecchia. Fino a 10 chiavi attive per negozio per un passaggio graduale. | |
| 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. | |
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.
| Piano | Richieste al minuto | Breve termine (burst) | Contemporanee |
|---|---|---|---|
| Free | 60 | 120 | 5 |
| Basic | 120 | 240 | 10 |
| Pro | 300 | 600 | 25 |
| Business | 600 | 1200 | 50 |
| Custom | 2000 | concordato | concordato |
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.
| Codice | Lato | Significato | Cosa fai |
|---|---|---|---|
| 400 | Client | Bad request — corpo o query malformato | Verifica la forma della richiesta rispetto al file OpenAPI. |
| 401 | Client | Non autorizzato — chiave API mancante o invalida | Invia l'header X-API-Key con una chiave pm_live_ o pm_test_ valida. |
| 402 | Client | Pagamento richiesto — limite del piano raggiunto | Cambia piano o aspetta il prossimo ciclo. Usa «Recupera» (bulk reconciliation) dopo il cambio. |
| 403 | Client | Vietato — accesso negato | Verifica 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. |
| 404 | Client | Non trovato — risorsa inesistente | Verifica l'ID. L'ordine potrebbe non essere ancora sincronizzato. |
| 422 | Client | Non processabile — validazione semantica fallita | Leggi error.message — tipicamente dimensioni mancanti o materiale non valido. |
| 429 | Client | Troppe richieste — limite raggiunto | Attendi secondo l'header Retry-After. Vedi la tabella «Limiti per piano» sopra. |
| 500 | Server | Errore interno — bug dalla nostra parte | Riprova una volta, poi scrivi a support@packmate.shop con il request_id del corpo dell'errore. |
| 503 | Server | Servizio non disponibile — manutenzione o problema al database | Riprova 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.
| Tema | Tipo | Cosa fa PackMate |
|---|---|---|
| customers/redact | Richiesto | In 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_request | Richiesto | Un cliente richiede l'esportazione dei suoi dati. PackMate la compila entro 30 giorni. |
| shop/redact | Richiesto | Shopify lo invia circa 48 ore dopo la disinstallazione. PackMate elimina quindi tutti i dati del negozio dal proprio database. |
| app/uninstalled | Richiesto | L'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/update | Opzionale | Prodotto modificato — PackMate aggiorna dimensioni e metafields in cache. |
| app/scopes_update | Opzionale | Scope 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.