Guida di riferimento all'API REST

Tutti i percorsi sono relativi a https://shopify.workflow-transactional-email.app. Ogni endpoint, ad eccezione dell’indice, richiede Authorization: Bearer fak_... - si veda Autenticazione e chiavi API.

Le risposte sono in formato JSON. Gli errori assumono sempre la stessa struttura:

{ "error": "Invalid or missing API key" }

Indice e identità

Metodo	Percorso	Livello	Finalità
GET	/api/v1	nessuno	Indice API. Conferma che l'API è attiva e riporta la versione corrente
GET	/api/v1/me	leggere	Verifichi il funzionamento di una chiave e ne controlli il livello di accesso

L'indice non richiede alcuna chiave, pertanto rappresenta un indicatore affidabile su cui concentrare il monitoraggio.

Layout delle e-mail

Metodo	Percorso	Livello	Finalità
GET	/api/v1/email-templates	leggere	Elenco dei layout delle e-mail. q consente di effettuare ricerche per nome, oggetto e descrizione; category=transactional o category=marketing elenca un tipo di e-mail
POST	/api/v1/email-templates	scrivere	Creare un layout
GET	/api/v1/email-templates/:id	leggere	Un layout con il proprio design o i propri allegati, i testi del piè di pagina e l'elenco delle lingue disponibili
PUT / PATCH	/api/v1/email-templates/:id	scrivere	Modificare un layout. Verranno modificati solo i campi che inviate
ELIMINA	/api/v1/email-templates/:id	scrivere	Eliminare un layout con le relative traduzioni e versioni
GET	/api/v1/layout-schema	leggere	Come scrivere un layout: il formato di progettazione, le impostazioni predefinite di ogni blocco, il codice Liquid che è possibile utilizzare, i limiti e un esempio

L'elenco accetta page (valore predefinito 1), limit (valore predefinito 25, massimo 100) e q, che effettua la ricerca per nome, oggetto e descrizione. L'API non prevede alcun filtro per tipo; si prega di consultare invece category per ciascun layout.

Un layout presenta i seguenti campi:

Campo	Note
name, description	Nome obbligatorio, massimo 200 caratteri; descrizione: massimo 2000
bodyType	visual (impostazione predefinita) oppure text. Una volta creato, rimane fisso
defaultLocale	La lingua dei contenuti del layout stesso, en, salvo diversa impostazione
category	transactional (impostazione predefinita) oppure marketing. Si veda di seguito
subject, previewText	È consentito portare liquidi. È obbligatorio presentarsi.
bodyDesign	Layout grafici: { blocks, global?, header?, footer?, testVariables? }. In caso di modifiche, inviate il progetto completo; il codice HTML body viene generato a partire da esso
body	Impaginazione del testo: il corpo HTML
attachments	Layout di testo: [{ filename, fileKey, sendAsLink? }] per i file caricati (vedere i file riportati di seguito) oppure [{ filename, url }] per un file recuperato tramite https al momento dell’invio dell’e-mail
marketingTexts	I testi del piè di pagina di un layout di marketing, ovvero null. Si veda di seguito

Il testo “Liquid” nel campo “subject”, nell’anteprima, nel corpo del testo e in ogni blocco di testo deve essere analizzato, e ogni fileKey deve appartenere al Suo negozio; in caso contrario, la scrittura verrà rifiutata con un codice di errore 400 che indica il campo in questione. Legga GET /api/v1/layout-schema prima di creare un progetto visivo: esso viene generato dal builder stesso, pertanto non può subire variazioni.

Ogni operazione di scrittura effettuata tramite questa API viene registrata nella cronologia delle versioni del layout, esattamente come un salvataggio nell’app.

Layout transazionali e di marketing

category spiega a cosa serve un layout. Un layout transazionale viene inviato a tutti i destinatari, senza alcuna modifica. Un layout di marketing esclude i destinatari che si sono disiscritti (una fase in cui il messaggio «To recipients all unsubscribed» non viene inviato e viene visualizzata la dicitura SKIPPED nella cronologia), viene inviato come un unico messaggio per ciascun destinatario del campo «To» con il proprio link di disiscrizione (al massimo 20 per fase) e termina con la frase di disiscrizione e i dati della vostra azienda. {{ unsubscribe_url }} e {{ unsubscribe_link }}: inserisca il link autonomamente; nei layout transazionali entrambi i campi sono vuoti. Le informazioni relative ai merchant sono disponibili all’indirizzo E-mail di marketing e cancellazioni dall’iscrizione.

marketingTexts Il testo del piè di pagina è quello utilizzato da un layout di marketing al posto dei testi applicati a tutto il negozio presenti in “Impostazioni”:

{
  "marketingTexts": {
    "unsubscribeText": "You get this because you shop with us. {{ unsubscribe_link }}",
    "unsubscribeLinkLabel": "Unsubscribe",
    "companyDetails": "Example GmbH, Musterstrasse 1, 10115 Berlin"
  }
}

Ogni campo è facoltativo. Se un campo viene compilato, il testo "Impostazioni" relativo a quel campo viene sostituito; gli altri rimangono invariati. null (impostazione predefinita) indica i testi delle impostazioni corrispondenti alla lingua dell'e-mail. Limiti: unsubscribeText e companyDetails 2000 caratteri, unsubscribeLinkLabel 100. Un campo unsubscribeText deve contenere {{ unsubscribe_link }} o {{ unsubscribe_url }}, altrimenti la scrittura viene rifiutata. Il campo viene memorizzato per qualsiasi layout, ma inviato solo con quelli di marketing.

L'eliminazione di un layout non viene mai bloccata. Se alcuni passaggi di unShopify Flowe fanno ancora riferimento a tale layout, la risposta riporta un warning che ne indica il numero; tali passaggi falliscono finché non viene utilizzato un altro layout.

Traduzioni

Metodo	Percorso	Livello	Finalità
GET	/api/v1/email-templates/:id/translations	leggere	Ogni lingua di un layout con il relativo contenuto
GET	/api/v1/email-templates/:id/translations/:locale	leggere	Una lingua
PUT	/api/v1/email-templates/:id/translations/:locale	scrivere	Creare o sostituire una lingua
ELIMINA	/api/v1/email-templates/:id/translations/:locale	scrivere	Eliminare una lingua. In tal caso, si tornerà al layout predefinito
POST	/api/v1/email-templates/:id/translations/:locale/promote	scrivere	Impostare tale lingua come lingua principale del layout

:locale è un codice lingua del tipo de, fr o pt-br; non è rilevante la distinzione tra maiuscole e minuscole né il separatore. Sono ammesse fino a 30 lingue per ogni layout. Il campo “Lingua” della fase Shopify Flow ne seleziona una al momento dell’invio: la locale esatta, poi la lingua di base, poi una variante regionale, altrimenti il layout stesso.

Un file PUT deve contenere l'intero contenuto tradotto: subject (obbligatorio), previewText e bodyDesign (immagine) oppure body (testo). Si prega di mantenere invariati i tag Liquid e gli URL. Due campi sono specifici della traduzione:

Campo	Impaginazione del testo	Significato
attachments	sì	Un elenco (della stessa struttura del layout) = allegati propri di questa lingua, [] = nessuno in questa lingua. null = inviare gli allegati del layout. Omesso = mantenere la scelta corrente; una nuova lingua utilizza quelli del layout. I layout visivi contengono i propri allegati come blocchi nel file bodyDesign di ciascuna lingua e ignorano questo campo
marketingTexts	qualsiasi	I testi di piè di pagina di questa lingua si sovrappongono a quelli del layout, campo per campo. null = quelli del layout. “Omitted” = mantenere la scelta attuale

Viene restituita una traduzione con gli stessi due campi: attachments corrisponde a null, pur utilizzando il layout, mentre marketingTexts corrisponde a null, pur utilizzando il layout.

promote scambia il layout e la traduzione: il layout assume il contenuto e le impostazioni locali della traduzione, mentre il contenuto che possedeva in precedenza diventa la traduzione per la lingua in cui era originariamente impostato. Anche gli allegati e i testi del piè di pagina si scambiano di posto, in modo che ogni lingua continui a inviare ciò che inviava in precedenza. La risposta riporta promoted, previousMainLanguage e il layout. Si tratta di una singola versione, pertanto è possibile annullarla.

Versioni

Metodo	Percorso	Livello	Finalità
GET	/api/v1/email-templates/:id/versions	leggere	Versioni salvate, in ordine cronologico (dalle più recenti alle più vecchie). L’app conserva le ultime 25
GET	/api/v1/email-templates/:id/versions/:version	leggere	L'istantanea completa di una versione: layout e tutte le traduzioni
POST	/api/v1/email-templates/:id/versions/:version/restore	scrivere	Ripristini quella versione. Registrata come nuova versione
GET	/api/v1/email-templates/:id/versions/github?page=	leggere	Tutte le versioni conservate nel repository GitHub collegato, 20 per pagina
GET	/api/v1/email-templates/:id/versions/github/:sha	leggere	Il layout così come appariva in un determinato commit
POST	/api/v1/email-templates/:id/versions/github/:sha/restore	scrivere	Ripristinare una versione di GitHub, come se si salvasse il lavoro

Gli endpoint di GitHub restituiscono il codice di errore 409 quando nella pagina "Developer" non è collegato alcun repository. Si vedano Cronologia delle versioni del layout e Conservate una cronologia illimitata dei layout su GitHub.

Mittenti delle e-mail

Metodo	Percorso	Livello	Finalità
GET	/api/v1/smtp-configs	leggere	Elenco dei mittenti SMTP
GET	/api/v1/senders	leggere	Elencare le caselle di posta collegate (Microsoft 365, Google)

I mittenti SMTP riportano hasUsername e hasPassword anziché le credenziali vere e proprie: entrambe le parti vengono omesse, poiché il nome utente è parte integrante delle credenziali tanto quanto la password. Un mittente rimane identificabile tramite il proprio nome, l’host e l’indirizzo del mittente. Le caselle di posta collegate riportano un indirizzo parzialmente mascherato, come ad esempio so***@example.com, e non rivelano mai i propri token di accesso.

Solo lettura. Si colleghino e si modifichino i mittenti nell'app.

Segreti

Metodo	Percorso	Livello	Finalità
GET	/api/v1/secrets	leggere	Elencare i nomi segreti e le descrizioni

Restituisce un oggetto hasValue, mai il valore stesso. Non esiste alcun endpoint che consenta di recuperare un segreto. Si prega di creare e aggiornare i segreti all’interno dell’applicazione.

File caricati

Metodo	Percorso	Livello	Finalità
GET	/api/v1/files	leggere	Elenco dei loghi, delle immagini e degli allegati caricati
ELIMINA	/api/v1/files	scrivere	Eliminare uno, di key nel corpo del testo

L'elenco accetta i formati page, limit (max 100) e q per effettuare la ricerca in base al nome del file.

Aggiunga ?usage=true: ogni file riporta anche inUse, oltre a un array usedBy che elenca i layout e i preset che vi fanno riferimento. In questo modo potrà individuare tutti gli elementi che può eliminare in tutta sicurezza con un’unica richiesta. Poiché questa funzione esegue una scansione dei Suoi layout e preset, è attivabile su richiesta anziché essere predefinita.

In questa sezione non è disponibile la funzione di caricamento: si prega di aggiungere i file tramite il selettore multimediale presente nell’app.

Richieste HTTP

Metodo	Percorso	Livello	Finalità
GET	/api/v1/http-requests	leggere	Elencare le richieste HTTP
POST	/api/v1/http-requests	scrivere	Crearne uno
GET	/api/v1/http-requests/:id	leggere	Ne acquisti uno
PUT / PATCH	/api/v1/http-requests/:id	scrivere	Aggiornamento n. 1
ELIMINA	/api/v1/http-requests/:id	scrivere	Eliminarne uno
POST	/api/v1/http-requests/:id/test	eseguire	Eseguatelo sul bersaglio reale

List accetta gli stessi parametri page, limit e q utilizzati per i layout delle e-mail.

L'urle di destinazione deve essere http:// o https://. Altri schemi vengono rifiutati al momento del salvataggio.

Le credenziali inserite letteralmente nell’intestazione o nel corpo del messaggio vengono mascherate in ogni risposta. I valori a cui si fa riferimento tramite {{ secrets.KEY }} vengono restituiti così come sono stati inseriti, poiché il riferimento stesso non è sensibile.

Storia e statistiche

Riguarda sia l’invio di e-mail che le richieste HTTP.

Metodo	Percorso	Livello	Finalità
GET	/api/v1/history	leggere	Esecuzioni di liste
GET	/api/v1/history/:id	leggere	Ottenere un'esecuzione con i dati della richiesta e della risposta
GET	/api/v1/stats	leggere	Totali e percentuale di successo

La proprietà “History” accetta i valori page, limit (max 100), actionType, status (PENDING, SUCCESS, FAILED, SKIPPED) e actionConfigId per filtrare i risultati in base a un singolo layout o a una singola richiesta.

SKIPPED Si tratta di un’e-mail di marketing i cui destinatari si erano tutti cancellati dalla mailing list: non è stato inviato nulla, non è stata utilizzata alcuna quota e non viene conteggiata ai fini del tasso di successo.

actionType Deve essere esattamente EMAIL o HTTP_REQUEST. Un valore non riconosciuto viene ignorato anziché respinto, pertanto un errore di digitazione restituisce tutti i risultati anziché generare un errore.

Stats accetta valori compresi tra days (valore predefinito 30, massimo 365).

Codici di stato

Codice	Significato
200	Successo
201	Creato
400	Richiesta non corretta o convalida non riuscita. Il parametro error indica il nome del campo, ad esempio subject: required
401	Chiave API mancante, non valida o revocata
403	La chiave è valida, ma il suo livello è troppo basso per questo endpoint
404	Non trovato, oppure appartiene a un altro negozio
405	Metodo errato per questo percorso
409	Richiesta rifiutata poiché il record è ancora in uso (eliminazione di file) oppure GitHub non è connesso (versioni GitHub)
429	Limite di frequenza - si veda di seguito
502	La richiesta è stata eseguita, ma il target di terze parti non ha funzionato

Un record appartenente a un altro negozio restituisce il codice 404 anziché 403, pertanto l’API non conferma mai l’esistenza di un ID in un altro contesto.

Limiti di frequenza

Due bilanci indipendenti, entrambi per chiave:

• 300 richieste ogni 60 secondi su tutti gli endpoint.
• Oltre a ciò, vengono effettuate 60 chiamate all’ora, che riguardano l’POST /api/v1/http-requests/:id/teste.

Il superamento di uno dei due limiti restituisce il codice di errore 429 con la spiegazione error. Il budget di esecuzione è volutamente limitato: un ciclo fuori controllo che invia richieste in tempo reale a un fornitore di servizi di pagamento rappresenta un errore ben più grave rispetto a uno script lento.

I budget sono assegnati per chiave, non per negozio, pertanto un’integrazione non può esaurire la quota a disposizione di un’altra.