API per sviluppatori, MCP, GitHub e simulazione dei trigger
Puoi controllare i tuoi trigger, attivarli o disattivarli, consultare la cronologia degli eventi e simulare un trigger dal tuo codice o da un assistente IA. Workflow Trigger Extensions mette a disposizione un'API REST e un server MCP, e può connettersi a un repository GitHub in modo che il tuo codice personalizzato per i trigger sia sottoposto al controllo di versione. Tutti e tre questi elementi sono gestiti nella pagina "Developer".
Simulazione di un trigger
Testare un flusso di lavoro in Flow significa normalmente riprodurre la situazione reale nel proprio negozio: modificare un prodotto, effettuare un ordine, attendere il risultato di un sondaggio. La simulazione elimina questa attesa: basta scegliere un trigger, associarlo a una risorsa e questo si attiverà come se l'evento reale fosse appena avvenuto.
Due modi per eseguirne uno:
- Nell'app. Apri un evento qualsiasi nella Cronologia eventi e seleziona nuovamente "Simula". In questo modo verrà riattivato proprio quell'evento.
- Tramite l'API o l'MCP, utilizzando un ID risorsa o un evento passato.
La simulazione è volutamente fedele. Non crea un payload abbreviato, ma segue lo stesso percorso di un vero webhook di Shopify; pertanto, ciò che il tuo flusso di lavoro riceve è esattamente ciò che riceverebbe in produzione.
curl -X POST https://shopify.workflow-trigger-extensions.app/api/v1/triggers/product-update-trigger/simulate \
-H "Authorization: Bearer ftk_your_key_here" \
-H "Content-Type: application/json" \
-d '{"resourceId":"gid://shopify/Product/123456789","dryRun":true}'Un test di prova verifica il trigger, risolve l'argomento e mostra il payload, senza attivare nulla. Rimuovi dryRun per attivarlo realmente. Puoi anche passare {"fromHistoryId":"456"} per riattivare un evento passato invece di crearne uno nuovo.
I trigger basati sul polling anziché su un webhook non possono essere simulati; nell'elenco dei trigger viene segnalato il messaggio simulatable: false.
Chiavi API
Crea una chiave nella pagina "Sviluppatori" e seleziona il relativo livello di accesso:
- Solo lettura: elenca i trigger e il loro stato, visualizza la cronologia degli eventi, le statistiche e le autorizzazioni.
- Lettura e scrittura - oltre all'attivazione e alla disattivazione dei trigger.
- Lettura, scrittura ed esecuzione: è inoltre possibile simulare i trigger e testare il codice dei trigger personalizzati.
La chiave completa viene visualizzata una sola volta, al momento della creazione. Le chiavi vengono memorizzate sotto forma di hash e possono essere revocate in qualsiasi momento. Invia la chiave come token Bearer:
Authorization: Bearer ftk_your_key_hereLa simulazione si colloca a un livello inferiore proprio per il motivo sopra indicato: esegue effettivamente le automazioni, quindi una chiave utilizzata per le letture quotidiane non può attivarle.
API REST
| Metodo | Percorso | Livello | Scopo |
|---|---|---|---|
| OTTIENI | /api/v1 |
nessuno | Indice API - conferma che l'API è attiva |
| OTTIENI | /api/v1/me |
leggi | Verifica l'autenticazione e controlla il livello della tua chiave |
| OTTIENI | /api/v1/triggers |
leggi | Ogni trigger, con il relativo stato per il tuo negozio |
| OTTIENI | /api/v1/triggers/:handle |
leggi | Un fattore scatenante in dettaglio |
| PUT | /api/v1/triggers/:handle |
scrivere | Attivare o disattivare un trigger |
| PUT | /api/v1/triggers |
scrivere | Attivare o disattivare più elementi con un'unica chiamata |
| POST | /api/v1/triggers/:handle/simulate |
eseguire | Simulare un trigger |
| OTTIENI | /api/v1/triggers/custom |
leggi | I tuoi trigger personalizzati, con il relativo codice |
| OTTIENI | /api/v1/triggers/custom/:handle/test |
leggi | L'evento relativo al campione acquisito per un trigger personalizzato |
| POST | /api/v1/triggers/custom/:handle/test |
eseguire | Esegui il codice di un trigger personalizzato senza salvarlo né attivarlo |
| OTTIENI | /api/v1/history |
leggi | Elenco degli eventi di attivazione |
| OTTIENI | /api/v1/history/:id |
leggi | Recupera un evento con il relativo payload |
| OTTIENI | /api/v1/stats |
leggi | Totali, percentuale di successo, ripartizione per stato |
| OTTIENI | /api/v1/permissions |
leggi | Quali autorizzazioni relative ai dati hai concesso e quali funzionalità sbloccano |
GET /api/v1/triggers È molto utile per la configurazione: per ogni trigger indica l'autorizzazione necessaria, se tale autorizzazione è stata concessa, se il trigger è attivo e dove gestirlo all'interno dell'app.
Attivazione e disattivazione dei trigger
PUT Si utilizza questa funzione anziché PATCH perché la chiamata è idempotente: ripeterla dopo un timeout non comporta una doppia applicazione, aspetto importante quando l'API è gestita da un assistente.
curl -X PUT https://shopify.workflow-trigger-extensions.app/api/v1/triggers/order-tags-added-trigger \
-H "Authorization: Bearer ftk_your_key_here" \
-H "Content-Type: application/json" \
-d '{"enabled":true}'L'abilitazione non concede mai un'autorizzazione. Se il trigger richiede un'autorizzazione che non hai concesso, la chiamata va comunque a buon fine e ti indica esattamente cosa manca e dove concederla:
{
"enabled": true,
"scopeGranted": false,
"missingScopeLabels": ["Order Data Access"],
"permissionsUrl": "https://admin.shopify.com/store/.../app/permissions?permission=read_orders",
"warning": "Enabled, but this trigger cannot fire until Order Data Access is granted."
}Quel link apre la pagina "Permessi" con lo scorrimento già posizionato direttamente sulla scheda che ti serve.
Aggiungi "sync": true per avviare anche la sincronizzazione dei dati, in modo che il trigger agisca sui record già esistenti anziché solo su quelli creati d'ora in poi.
Per cambiare più impostazioni contemporaneamente, PUT /api/v1/triggers accetta un elenco esplicito o un'intera categoria:
{ "enabled": true, "handles": ["order-tags-added-trigger", "order-note-changed-trigger"] }
{ "enabled": true, "category": "orders" }Collega GitHub
Nella pagina "Sviluppatori", la scheda "Connessioni" ti consente di collegare un repository GitHub per il codice di Trigger personalizzati. Le modifiche diventano disponibili per la revisione in una pull request; puoi vedere chi ha apportato quali modifiche e puoi ripristinare una trasformazione che ha smesso di funzionare.
Selezionando “Connetti” si installa la nostra app GitHub sull’account che scegli. Sei tu a decidere a quali repository l’app può accedere e puoi revocare tale accesso da GitHub in qualsiasi momento. Selezionando un repository, tutti i trigger personalizzati già presenti vengono immediatamente salvati al suo interno, in modo che l’app sia subito sincronizzata con esso, anziché completarsi gradualmente nel tempo.
| Cosa fai | Cosa succede |
|---|---|
| Crea, modifica o duplica un trigger nell'app | Il file è stato salvato nel tuo repository |
| Eliminare un trigger nell'app | Il file viene rimosso dal tuo repository |
| Invia una modifica al ramo collegato | Il codice del trigger viene aggiornato nell'app |
Ogni trigger è un file il cui nome corrisponde al proprio handle e che contiene esattamente il modulo visualizzato nell'editor, senza alcun codice aggiuntivo. È quindi possibile aprirlo nel proprio editor, eseguirlo e sottoporlo a lint come qualsiasi altro file JavaScript, quindi utilizzare l'endpoint /test sopra indicato per eseguirlo su un evento reale catturato prima di effettuare il commit.
Tornare a una versione precedente
Non è necessario conoscere Git per annullare una modifica. Una volta collegato un repository, l’editor di trigger mostra un menu a tendina “Versione” che elenca tutte le versioni precedenti di quel file con la rispettiva data e autore. Scegline una e questa verrà caricata nell’editor come modifica non salvata, così potrai prima leggerla; è il salvataggio che la ripristina, come nuovo commit.
Modifica o disconnessione
L'opzione "Cambia repository" ti riporta alla schermata di selezione senza modificare l'installazione. L'opzione "Disconnetti" revoca l'installazione su GitHub e la rimuove anche da qui, quindi fa esattamente ciò che dice. L'opzione "Gestisci autorizzazioni" apre le impostazioni di installazione su GitHub, dove puoi aggiungere o rimuovere repository.
Test del codice di trigger personalizzato
Se conservi il codice del trigger personalizzato in un repository e lo modifichi nel tuo editor, puoi eseguirlo sull'evento di esempio acquisito senza doverlo prima salvare nell'app.
curl -X POST https://shopify.workflow-trigger-extensions.app/api/v1/triggers/custom/my-trigger/test \
-H "Authorization: Bearer ftk_your_key_here" \
-H "Content-Type: application/json" \
-d "$(jq -Rn --rawfile c flow-triggers/my-trigger.js '{code:$c}')"Si ottiene ciò che viene visualizzato dal pulsante “Test” dell’app: se il codice verrebbe eseguito, l’oggetto di output, le righe di codice ctx.log e il tempo di esecuzione.
Non viene eseguito alcun comando e non viene salvato nulla: non viene avviato alcun flusso di lavoro, non viene registrato alcun evento, non viene utilizzata alcuna quota e il codice memorizzato rimane inalterato. È possibile eseguirlo in tutta sicurezza ad ogni salvataggio da un file watcher. Per il flusso di lavoro completo, consultare Trigger personalizzati.
Server MCP
La scheda MCP nella pagina “Sviluppatori” mostra l’URL del server e un comando di connessione pronto per essere copiato per Claude, Cursor, VS Code, Gemini CLI e altri. Gli strumenti rispecchiano gli endpoint REST e il set di strumenti riflette il livello della tua chiave: una chiave di sola lettura non consente affatto l’accesso agli strumenti di scrittura o di esecuzione.
| Strumento | Livello | Cosa fa |
|---|---|---|
list_triggers |
leggi | Ogni trigger e il relativo stato |
list_custom_triggers |
leggi | I tuoi trigger personalizzati, con il relativo codice |
get_custom_trigger_sample |
leggi | L'evento intercettato rispetto al quale viene eseguito il test di un trigger personalizzato |
list_history |
leggi | Eventi scatenanti recenti |
get_event |
leggi | Un evento comprensivo del suo carico utile |
get_stats |
leggi | Statistiche aggregate |
get_permissions |
leggi | Autorizzazioni concesse e cosa consentono di sbloccare |
get_trigger |
scrivere | Un fattore scatenante in dettaglio |
set_trigger |
scrivere | Attivare o disattivare un trigger |
set_triggers_bulk |
scrivere | Accendere o spegnere più dispositivi contemporaneamente |
simulate_trigger |
eseguire | Attivare un trigger su richiesta |
test_custom_trigger |
eseguire | Esegui il codice di un trigger personalizzato senza salvare né attivare il trigger |
Ecco cosa rende un assistente davvero utile: è in grado di elencare ciò che è presente, spiegare cosa serve a un trigger, attivarlo, generare un evento di prova, riportare il risultato e, nel caso di trigger personalizzati, riscrivere il codice e testarlo, il tutto senza che tu debba uscire dalla conversazione.
Come vengono protetti i tuoi dati
I payload degli eventi vengono restituiti con i dati personali mascherati: indirizzi e-mail, numeri di telefono, numeri di carta di credito e campi contenenti nomi di persone vengono sostituiti con ***. Gli ID delle risorse Shopify e i campi relativi all'azienda vengono lasciati intatti, in modo che il payload rimanga utilizzabile.
La mascheratura agisce sui nomi dei campi e sui modelli di valore, quindi è un provvedimento accurato ma non offre alcuna garanzia: i dati personali contenuti in un campo di testo libero potrebbero comunque essere visibili. Anche i messaggi di errore vengono privati dei dettagli diagnostici interni prima di lasciare il server.
La connessione a GitHub non memorizza alcuna credenziale che possa essere compromessa: viene conservato solo l'ID di installazione, mentre l'accesso al repository avviene tramite un token generato al momento, che scade entro un'ora.
Prossimi passi
- Trigger personalizzati - crea un trigger personalizzato con poche righe di JavaScript.
- Piani e utilizzo - cosa si intende per "evento" e come funziona l'indennità.
- Introduzione a Workflow Trigger Extensions - come funzionano i trigger e come attivarli.
Limiti di frequenza
L'API REST e il server MCP condividono un unico budget per ogni chiave API.
- 300 richieste ogni 60 secondi per chiave, in una finestra fissa.
- Le chiamate a livello di esecuzione dispongono di un secondo limite, più restrittivo, pari a 60 all’ora. Poiché consumano entrambi i limiti, una serie concentrata di esecuzioni intacca anche la quota condivisa. Per questa app ciò significa simulare un trigger ed eseguire codice di trigger personalizzato, entrambe operazioni che attivano effettivamente i flussi di lavoro.
- È lo stesso per tutti i piani. Sono i contatori del tuo piano a innescare gli eventi, non le chiamate API, quindi l'aggiornamento non fa aumentare questi numeri.
- Se si verifica un codice di risposta HTTP 429, attendere e riprovare, preferibilmente con un backoff esponenziale.
- Se la nostra cache dovesse risultare temporaneamente non disponibile, il limitatore agirà in modalità “fail-open” anziché bloccare la tua integrazione.
I webhook in entrata di Shopify non sono soggetti a limitazioni di frequenza
Non limitiamo i webhook che ci invia Shopify: vengono accettati man mano che arrivano e messi in coda. Il limite massimo è rappresentato dal numero di eventi consentiti dal tuo piano nei 30 giorni.
Una cosa che vale la pena sapere se scrivi trigger personalizzati: il tuo codice viene eseguito per ogni evento dell'argomento che ascolta, e ogni esecuzione conta come un evento, compresi quelli che filtri via restituendo un valore null. Il costo è lo stesso che avrebbe un trigger integrato per lo stesso evento.
Shopify
Si tratta dei limiti imposti da Shopify sulle API di Shopify, non dei nostri. Questi limiti riguardano ciò che questa app (e i tuoi flussi di lavoro) può fare sul lato Shopify, e potresti raggiungerli se gestisci un negozio di grandi dimensioni, anche se rimani ben al di sotto dei nostri limiti.
- Gli array in ingresso sono limitati a 250 elementi in tutte le API di Shopify. Una richiesta contenente un array più grande viene rifiutata.
- L'impaginazione si interrompe a 25.000 oggetti. I conteggi sono precisi fino a 25.000; oltre tale limite, Shopify restituisce
25001, ovvero "più di 25.000". Se è necessario andare oltre, applicare prima un filtro. - L'API di amministrazione GraphQL viene misurata in base al costo calcolato delle query, espresso in punti al secondo, e il limite massimo dipende dal piano Shopify del negozio:
| Shopify piano | Punti al secondo |
|---|---|
| Standard | 100 |
| Avanzato | 200 |
| Inoltre | 1000 |
| Enterprise (Componenti commerciali) | 2000 |
L'API Storefront non è soggetta a limiti di frequenza.
Dettagli completi: Shopify Limiti di richiesta API