API per sviluppatori, MCP, GitHub e simulazione dei trigger

Potete controllare i vostri trigger, attivarli o disattivarli, consultare la cronologia degli eventi e simulare un trigger dal vostro codice o da un assistente IA. Workflow Trigger Extensions mette a disposizione un'API REST e un server MCP, ed è in grado di connettersi a un repository GitHub in modo che il vostro 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 workflow in Shopify 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 tale attesa: basta selezionare un trigger, associarlo a una risorsa e questo si attiverà come se l’evento reale si fosse appena verificato.

Due modi per eseguirne uno:

• Nell'app. Aprite un evento qualsiasi nella Cronologia eventi e selezionate 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 seguito da un vero webhook di Shopify; pertanto, ciò che il Vostro workflow 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 simulazione verifica il trigger, risolve l’argomento e mostra il payload, senza attivare alcuna azione. Rimuovete dryRun per attivarlo realmente. Potete inoltre passare {"fromHistoryId":"456"} per riattivare un evento passato anziché crearne uno nuovo.

Triggers basati sul polling anziché su un webhook non possono essere simulati; nell’elenco dei trigger viene segnalato il messaggio simulatable: false.

Chiavi API

Crei una chiave nella pagina "Sviluppatori" e ne selezioni il livello di accesso:

• Sola lettura: visualizzare i trigger e il loro stato, consultare la cronologia degli eventi, le statistiche e le autorizzazioni.
• Lettura e scrittura - nonché attivazione e 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. La invii come token Bearer:

Authorization: Bearer ftk_your_key_here

La simulazione si colloca a un livello superiore rispetto alle altre per il motivo sopra indicato: esegue effettivamente le automazioni, pertanto una chiave utilizzata per le letture quotidiane non può attivarle.

API REST

Metodo	Percorso	Livello	Finalità
GET	/api/v1	nessuno	Indice API - conferma che l’API è attiva
GET	/api/v1/me	leggere	Verifichi l’autenticazione e controlli il livello della Sua chiave
GET	/api/v1/triggers	leggere	Ogni trigger, con il relativo stato per il Suo negozio
GET	/api/v1/triggers/:handle	leggere	Un trigger in dettaglio
PUT	/api/v1/triggers/:handle	scrivere	Attivare o disattivare un trigger
PUT	/api/v1/triggers	scrivere	Attivare o disattivare più dispositivi con un’unica chiamata
POST	/api/v1/triggers/:handle/simulate	eseguire	Simulare un trigger
GET	/api/v1/triggers/custom	leggere	I Suoi trigger personalizzati, con il relativo codice
GET	/api/v1/triggers/custom/:handle/test	leggere	L'evento relativo al campione acquisito per un trigger personalizzato
POST	/api/v1/triggers/custom/:handle/test	eseguire	Eseguire il codice di un trigger personalizzato senza salvarlo né attivarlo
GET	/api/v1/history	leggere	Elencare gli eventi di attivazione
GET	/api/v1/history/:id	leggere	Recuperare un evento, con il relativo payload
GET	/api/v1/stats	leggere	Totali, percentuale di successo, ripartizione per stato
GET	/api/v1/permissions	leggere	Quali autorizzazioni relative ai dati ha concesso e quali funzionalità sbloccano

GET /api/v1/triggers È uno strumento utile per la configurazione: per ogni trigger indica l’autorizzazione richiesta, se tale autorizzazione è stata concessa, se il trigger è attivato e in quale sezione dell’app è possibile gestirlo.

Attivazione e disattivazione dei trigger

PUT Si utilizza questa funzione anziché PATCH poiché la chiamata è idempotente: la sua ripetizione dopo un timeout non comporta l’applicazione doppia di alcuna operazione, aspetto rilevante quando un assistente gestisce l’API.

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 avete concesso, la chiamata va comunque a buon fine e vi 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."
}

Tale link apre la pagina "Autorizzazioni" con lo scorrimento già posizionato direttamente sulla scheda che Le serve.

Aggiunga "sync": true per avviare anche una sincronizzazione dei dati, in modo che il trigger agisca sui record già esistenti anziché solo su quelli creati d’ora in poi.

Per selezionarne più di uno alla volta, 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" }

Collegare GitHub

Nella pagina “Sviluppatori”, la scheda “Connessioni” Le consente di collegare un repository GitHub per il Suo codice Trigger personalizzato. Le modifiche diventano disponibili per la revisione in una richiesta di pull; potrà vedere chi ha apportato quali modifiche e potrà ripristinare una trasformazione che ha smesso di funzionare.

Selezionando “Connetti” si installa la nostra app GitHub sull’account da Lei scelto. È Lei a decidere a quali repository l’app possa accedere e può revocare tale autorizzazione da GitHub in qualsiasi momento. Selezionando un repository, tutti i trigger personalizzati già in suo possesso vengono immediatamente salvati al suo interno, in modo che l’app sia immediatamente compatibile con esso anziché doversi adattare nel corso del tempo.

Di cosa si occupa	Cosa succede
Creare, modificare o duplicare un trigger nell'app	Il file è stato inserito nel Suo repository
Eliminare un trigger nell'app	Il file è stato rimosso dal Suo repository
Inviare una modifica al ramo collegato	Il codice del trigger viene aggiornato nell'app

Ogni trigger è costituito da un unico file il cui nome corrisponde al proprio handle, contenente 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; successivamente, è possibile utilizzare l’endpoint /test sopra indicato per eseguirlo su un evento reale acquisito 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 l’autore. Selezionatene una e questa verrà caricata nell’editor come modifica non salvata, in modo da poterla prima leggere; è solo salvandola che la si ripristina, come nuovo commit.

Modifica o disconnessione

L'opzione "Cambia repository" vi 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 indica. L'opzione "Gestisci autorizzazioni" apre le impostazioni di installazione su GitHub, dove è possibile aggiungere o rimuovere repository.

Verifica del codice di trigger personalizzato

Se conservate il codice del trigger personalizzato in un repository e lo modificate nel vostro editor, potete eseguirlo sull'evento campione 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}')"

Riceverà 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 workflow, non viene registrato alcun evento, non viene utilizzata alcuna quota e il codice memorizzato rimane inalterato. È possibile eseguire questa operazione in tutta sicurezza ad ogni salvataggio da un file watcher. Si veda Trigger personalizzato per il workflow completo.

Server MCP

La scheda MCP nella pagina "Developer" 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 vostra chiave: una chiave di sola lettura non ha alcuna visibilità sugli strumenti di scrittura o di esecuzione.

Strumento	Livello	Cosa fa
list_triggers	leggere	Ogni trigger e il relativo stato
list_custom_triggers	leggere	I Suoi trigger personalizzati, con il relativo codice
get_custom_trigger_sample	leggere	L'evento acquisito rispetto al quale viene effettuato il controllo da parte di un trigger personalizzato
list_history	leggere	Eventi scatenanti recenti
get_event	leggere	Un evento, compreso il suo payload
get_stats	leggere	Statistiche aggregate
get_permissions	leggere	Autorizzazioni concesse e relative funzionalità sbloccate
get_trigger	scrivere	Un trigger in dettaglio
set_trigger	scrivere	Attivare o disattivare un trigger
set_triggers_bulk	scrivere	Attivare o disattivare più elementi contemporaneamente
simulate_trigger	eseguire	Attivare un trigger su richiesta
test_custom_trigger	eseguire	Eseguire il codice di un trigger personalizzato senza salvare né attivare il trigger

Ecco ciò che rende un assistente davvero utile: è in grado di elencare ciò che è presente, spiegare di cosa ha bisogno un trigger, attivarlo, eseguire un evento di prova, riportare il risultato e, nel caso di trigger personalizzati, riscrivere il codice e testarlo, il tutto senza che l’utente debba uscire dalla conversazione.

Come vengono protetti i Suoi dati

Il payload degli eventi viene restituito con i dati personali oscurati: indirizzi e-mail, numeri di telefono, numeri di carta di credito e campi contenenti nomi propri 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 viene applicata ai nomi dei campi e agli schemi dei valori; pertanto, sebbene sia accurata, non costituisce** una garanzia**: i dati personali contenuti in un campo di testo libero potrebbero comunque essere rivelati. 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 oggetto di fuga: viene conservato solo l'ID di installazione, mentre l'accesso al repository avviene tramite un token generato su richiesta che scade entro un'ora.

Prossimi passi

• Trigger personalizzato - crei 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. Esse consumano entrambi i limiti; pertanto, una serie concentrata di esecuzioni intacca anche la quota condivisa. Per questa applicazione, ciò significa simulare un trigger ed eseguire codice di trigger personalizzato, entrambe operazioni che attivano effettivamente i Suoi workflow.
• È lo stesso per tutti i piani. Sono i contatori del Suo piano a trigger gli eventi, non le chiamate API, pertanto l’aggiornamento non comporta un aumento di tali valori.
• Viene restituito il codice di stato HTTP 429. Si prega di attendere e riprovare, preferibilmente con un backoff esponenziale.
• Qualora la nostra cache risultasse temporaneamente non disponibile, il limitatore adotterà una modalità di funzionamento "fail-open" anziché bloccare la vostra 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 Suo piano per un periodo di 30 giorni.

Una cosa che vale la pena sapere se scrivete trigger personalizzati: il vostro codice viene eseguito per ogni evento dell’argomento che ascolta, e ogni esecuzione conta come un evento, compresi quelli che filtrate 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 alle API di Shopify, non dei nostri. Essi si applicano a ciò che questa app (e i Suoi workflow) può fare sul lato Shopify, ed è possibile che li raggiunga nel caso di un negozio di grandi dimensioni, anche pur rimanendo ben al di sotto dei nostri limiti.

• Gli array di input sono limitati a 250 elementi in tutte le API di Shopify. Una richiesta contenente un array più ampio viene respinta.
• L'impaginazione si interrompe a 25.000 oggetti. I conteggi sono precisi fino a 25.000; oltre tale limite, lShopifye restituisce "25001, ovvero "più di 25.000". Se avete bisogno di approfondire la ricerca, applicate prima un filtro.
• L'API di amministrazione GraphQL è soggetta a limiti basati sul 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 della vetrina online non è soggetta a limitazioni di frequenza.

Dettagli completi: Limiti di richiesta dell’API di Shopify