Référence de l'API REST

Tous les chemins d'accès sont relatifs à https://shopify.workflow-transactional-email.app. Chaque point de terminaison, à l'exception de l'index, nécessite l'ajout de Authorization: Bearer fak_... - voir Authentification et clés API.

Les réponses sont au format JSON. Les erreurs présentent toutes la même structure :

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

Index et identité

Méthode	Chemin d'accès	Niveau	Objectif
OBTENIR	/api/v1	aucun	Index de l'API. Vérifie que l'API est opérationnelle et indique la version actuelle
OBTENIR	/api/v1/me	lire	Vérifiez si une clé fonctionne et consultez son niveau d'accès

Cet index ne nécessitant aucune clé, il constitue un indicateur fiable sur lequel vous pouvez vous appuyer pour effectuer un contrôle de bon fonctionnement.

Mises en page des e-mails

Méthode	Chemin d'accès	Niveau	Objectif
OBTENIR	/api/v1/email-templates	lire	Liste des modèles d'e-mails. q permet d'effectuer une recherche par nom, objet et description ; category=transactional ou category=marketing répertorie un type d'e-mail
PUBLICATION	/api/v1/email-templates	écrire	Créer une mise en page
OBTENIR	/api/v1/email-templates/:id	lire	Une mise en page avec son design ou ses annexes, ses textes de pied de page et la liste de ses langues
PUT / PATCH	/api/v1/email-templates/:id	écrire	Modifier une mise en page. Seuls les champs que vous envoyez sont modifiés
SUPPRIMER	/api/v1/email-templates/:id	écrire	Supprimer une mise en page ainsi que ses traductions et ses versions
OBTENIR	/api/v1/layout-schema	lire	Comment rédiger une mise en page : le format de conception, les paramètres par défaut de chaque bloc, le code Liquid que vous pouvez utiliser, les contraintes et un exemple

La liste accepte les paramètres suivants : page (valeur par défaut : 1), limit (valeur par défaut : 25, maximum : 100) et q, qui permet d'effectuer une recherche sur le nom, le sujet et la description. L'API ne propose pas de filtre par type ; veuillez plutôt consulter la page category pour chaque mise en page.

Une mise en page comporte les champs suivants :

Domaine	Remarques
name, description	Nom obligatoire, 200 caractères maximum ; description : 2 000 caractères maximum
bodyType	visual (par défaut) ou text. Ne peut plus être modifié une fois créé
defaultLocale	La langue du contenu propre à la mise en page, en, sauf indication contraire
category	transactional (par défaut) ou marketing. Voir ci-dessous
subject, previewText	Boissons autorisées. Matière obligatoire
bodyDesign	Mises en page visuelles : { blocks, global?, header?, footer?, testVariables? }. Veuillez envoyer la mise en page complète lorsque vous la modifiez ; le code HTML body est généré à partir de celle-ci.
body	Mise en page du texte : le corps HTML
attachments	Mise en page du texte : [{ filename, fileKey, sendAsLink? }] pour les fichiers téléchargés (voir les fichiers ci-dessous) ou [{ filename, url }] pour un fichier récupéré via https lors de l'envoi de l'e-mail
marketingTexts	Les textes de pied de page d'une mise en page marketing, ou null. Voir ci-dessous

Le texte « Liquid » dans le sujet, l'aperçu, le corps du texte et chaque bloc de texte doit être analysé, et chaque fileKey doit appartenir à votre boutique, faute de quoi l'écriture sera refusée avec un code d'erreur 400 indiquant le champ concerné. Veuillez consulter GET /api/v1/layout-schema avant de créer un design visuel : celui-ci est généré par le générateur lui-même, il ne peut donc pas diverger.

Chaque écriture effectuée via cette API est conservée dans l'historique des versions de la mise en page, exactement comme lors d'une sauvegarde dans l'application.

Mises en page transactionnelles et marketing

category explique à quoi sert un modèle. Un modèle transactionnel est envoyé à chaque destinataire, sans modification. Un modèle marketing ignore les destinataires qui se sont désabonnés (une étape pour laquelle le message « Tous les destinataires du champ « À » se sont désabonnés » n’est pas envoyé et apparaît sous la forme SKIPPED dans l’historique), est envoyé sous la forme d’un message par destinataire du champ « À » avec son propre lien de désabonnement (20 au maximum par étape), et se termine par la phrase de désabonnement et les coordonnées de votre entreprise. {{ unsubscribe_url }} et {{ unsubscribe_link }} : veuillez insérer vous-même le lien ; dans les modèles transactionnels, ces deux champs sont vides. Les informations destinées aux marchands se trouvent à l’adresse E-mails marketing et désabonnements.

marketingTexts Le texte du pied de page est-il celui utilisé par une mise en page marketing à la place des textes communs à toute la boutique définis dans les Paramètres :

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

Chaque champ est facultatif. Un champ renseigné remplace le texte « Paramètres » correspondant à ce champ ; les autres restent inchangés. null (valeur par défaut) signifie que les textes « Paramètres » correspondent à la langue de l’e-mail. Limites : unsubscribeText et companyDetails : 2 000 caractères ; unsubscribeLinkLabel : 100. Une adresse unsubscribeText doit contenir {{ unsubscribe_link }} ou {{ unsubscribe_url }}, faute de quoi l’écriture est refusée. Ce champ est enregistré pour tous les modèles, mais n’est envoyé qu’avec les modèles marketing.

La suppression d'une mise en page n'est jamais bloquée. Si certaines étapes dShopify Flows y font encore référence, la réponse contient un paramètre « warning indiquant leur nombre ; ces étapes échouent jusqu'à ce qu'elles utilisent une autre mise en page.

Traductions

Méthode	Chemin d'accès	Niveau	Objectif
OBTENIR	/api/v1/email-templates/:id/translations	lire	Chaque langue d'une mise en page avec son contenu
OBTENIR	/api/v1/email-templates/:id/translations/:locale	lire	Une seule langue
PUT	/api/v1/email-templates/:id/translations/:locale	écrire	Créer ou remplacer une langue
SUPPRIMER	/api/v1/email-templates/:id/translations/:locale	écrire	Supprimer une langue. En cas de problème, le système revient à la mise en page par défaut.
PUBLICATION	/api/v1/email-templates/:id/translations/:locale/promote	écrire	Définissez cette langue comme langue principale de la mise en page

:locale Il s'agit d'un code de langue tel que de, fr ou pt-br ; la casse et le séparateur n'ont pas d'importance. Jusqu'à 30 langues par mise en page. Le champ « Langue » de l'étape Shopify Flow en sélectionne une au moment de l'envoi : la locale exacte, puis la langue de base, puis une variante régionale, sinon la mise en page elle-même.

Un fichier PUT contient l'intégralité du contenu traduit : subject (obligatoire), previewText, ainsi que bodyDesign (visuel) ou body (texte). Veuillez ne pas modifier les balises Liquid ni les URL. Deux champs sont spécifiques à une traduction :

Domaine	Mise en page du texte	Signification
attachments	oui	Une liste (de même structure que celle de la mise en page) = les pièces jointes propres à cette langue, [] = aucune dans cette langue. null = envoyer les pièces jointes de la mise en page. Omis = conserver le choix actuel ; une nouvelle langue utilise celles de la mise en page. Les mises en page visuelles intègrent leurs pièces jointes sous forme de blocs dans le fichier bodyDesign de chaque langue et ignorent ce champ
marketingTexts	n'importe quel	Les textes de pied de page de cette langue s'affichent par-dessus ceux de la mise en page, champ par champ. null = ceux de la mise en page. « Omitted » = conserver le choix actuel

Une traduction est renvoyée avec les deux mêmes champs : attachments correspond à null lorsqu'elle envoie la mise en page, et marketingTexts correspond à null lorsqu'elle utilise la mise en page.

promote permet d'échanger la mise en page et la traduction : la mise en page reprend le contenu et les paramètres régionaux de la traduction, tandis que le contenu qu'elle contenait devient la traduction de la langue dans laquelle elle se trouvait auparavant. Les pièces jointes et les textes de pied de page échangent également leurs places, de sorte que chaque langue continue d’envoyer ce qu’elle envoyait auparavant. La réponse indique promoted, previousMainLanguage et la mise en page. Il s’agit d’une seule version, ce qui permet de revenir en arrière.

Versions

Méthode	Chemin d'accès	Niveau	Objectif
OBTENIR	/api/v1/email-templates/:id/versions	lire	Versions enregistrées, classées par ordre chronologique décroissant. L'application conserve les 25 plus récentes
OBTENIR	/api/v1/email-templates/:id/versions/:version	lire	L'instantané complet d'une version : mise en page et toutes les traductions
PUBLICATION	/api/v1/email-templates/:id/versions/:version/restore	écrire	Remettez cette version en ligne. Enregistrée en tant que nouvelle version
OBTENIR	/api/v1/email-templates/:id/versions/github?page=	lire	Toutes les versions conservées dans le dépôt GitHub associé, à raison de 20 par page
OBTENIR	/api/v1/email-templates/:id/versions/github/:sha	lire	La mise en page telle qu'elle se présentait lors d'un commit
PUBLICATION	/api/v1/email-templates/:id/versions/github/:sha/restore	écrire	Rétablir une version GitHub, comme lors d'une sauvegarde

Les points de terminaison GitHub renvoient un code d'erreur 409 lorsqu'aucun dépôt n'est associé à la page Développeur. Voir Historique des versions de la mise en page et Conservez un historique illimité des mises en page sur GitHub.

Expéditeurs d'e-mails

Méthode	Chemin d'accès	Niveau	Objectif
OBTENIR	/api/v1/smtp-configs	lire	Liste des expéditeurs SMTP
OBTENIR	/api/v1/senders	lire	Répertorier les boîtes aux lettres connectées (Microsoft 365, Google)

Les expéditeurs SMTP indiquent hasUsername et hasPassword plutôt que les identifiants proprement dits : les deux parties sont masquées, car le nom d'utilisateur fait tout autant partie des identifiants que le mot de passe. Un expéditeur reste identifiable grâce à son nom, à son hôte et à son adresse d'origine. Les boîtes aux lettres connectées indiquent une adresse partiellement masquée, telle que so***@example.com, et ne divulguent jamais leurs jetons de connexion.

En lecture seule. Connectez-vous et modifiez les expéditeurs dans l'application.

Secrets

Méthode	Chemin d'accès	Niveau	Objectif
OBTENIR	/api/v1/secrets	lire	Énumérez les noms secrets et leurs descriptions

Renvoie hasValue, jamais la valeur elle-même. Il n'existe aucun point de terminaison permettant de récupérer un secret. Créez et mettez à jour les secrets dans l'application.

Fichiers téléchargés

Méthode	Chemin d'accès	Niveau	Objectif
OBTENIR	/api/v1/files	lire	Liste des logos, images et pièces jointes téléchargés
SUPPRIMER	/api/v1/files	écrire	Supprimer l'un d'entre eux, par key dans le corps du texte

La liste accepte les formats page, limit (100 au maximum) et q pour effectuer une recherche par nom de fichier.

Ajoutez « ?usage=true » : chaque fichier renvoie également inUse, ainsi qu’un tableau usedBy répertoriant les mises en page et les préréglages qui y font référence. C’est ainsi que vous pouvez identifier tous les éléments que vous pouvez supprimer en toute sécurité en une seule requête. Cette fonctionnalité analyse vos mises en page et vos préréglages ; elle est donc activable manuellement et n’est pas activée par défaut.

La fonction de téléchargement n'est pas disponible ici : veuillez ajouter vos fichiers via la sélection de médias de l'application.

Requêtes HTTP

Méthode	Chemin d'accès	Niveau	Objectif
OBTENIR	/api/v1/http-requests	lire	Répertorier les requêtes HTTP
PUBLICATION	/api/v1/http-requests	écrire	En créer un
OBTENIR	/api/v1/http-requests/:id	lire	Achetez-en un
PUT / PATCH	/api/v1/http-requests/:id	écrire	Première mise à jour
SUPPRIMER	/api/v1/http-requests/:id	écrire	Supprimer l'un d'entre eux
PUBLICATION	/api/v1/http-requests/:id/test	exécuter	Testez-le sur la cible réelle

La liste accepte les mêmes paramètres page, limit et q que les modèles d'e-mail.

L'urle cible doit être http:// ou https://. Les autres schémas sont rejetés lors de l'enregistrement.

Les identifiants littéraux inscrits dans l'en-tête ou le corps d'un message sont masqués dans chaque réponse. Les valeurs référencées sous la forme {{ secrets.KEY }} sont renvoyées telles quelles, car la référence elle-même n'est pas sensible.

Historique et statistiques

Cela concerne à la fois les envois d'e-mails et les requêtes HTTP.

Méthode	Chemin d'accès	Niveau	Objectif
OBTENIR	/api/v1/history	lire	Exécutions de listes
OBTENIR	/api/v1/history/:id	lire	Obtenir une exécution avec les données de requête et de réponse
OBTENIR	/api/v1/stats	lire	Totaux et taux de réussite

History accepte les valeurs suivantes : page, limit (max. 100), actionType, status (PENDING, SUCCESS, FAILED, SKIPPED) et actionConfigId pour filtrer selon une seule mise en page ou une seule requête.

SKIPPED Il s'agit d'un e-mail marketing dont tous les destinataires s'étaient désabonnés : rien n'a été envoyé, aucun quota n'a été utilisé et cela n'est pas pris en compte dans le taux de réussite.

actionType doit correspondre exactement à EMAIL ou HTTP_REQUEST. Une valeur non reconnue est ignorée plutôt que rejetée ; ainsi, une faute de frappe renvoie le contenu complet au lieu de générer une erreur.

Le paramètre « stats » accepte des valeurs comprises entre days (valeur par défaut : 30, valeur maximale : 365).

Codes d'état

Code	Signification
200	Succès
201	Créé
400	Requête incorrecte ou validation échouée. L'errore indique le nom du champ, par exemple subject: required
401	Clé API manquante, incorrecte ou révoquée
403	La clé est valide, mais son niveau est trop faible pour ce point de terminaison
404	Introuvable, ou appartient à une autre boutique
405	Méthode incorrecte pour ce chemin d'accès
409	Opération refusée car l'enregistrement est encore utilisé (suppression de fichier) ou parce que GitHub n'est pas connecté (versions GitHub)
429	Limitation de débit - voir ci-dessous
502	La requête s'est exécutée, mais la cible tierce a échoué.

Une fiche appartenant à une autre boutique renvoie un code 404 au lieu d'un 403 ; l'API ne vérifie donc jamais si un identifiant existe déjà ailleurs.

Limites de débit

Deux budgets indépendants, tous deux par clé :

• 300 requêtes par 60 secondes sur l'ensemble des points de terminaison.
• En outre, 60 interventions par heure sont effectuées, notamment à l'adresse suivante : POST /api/v1/http-requests/:id/test.

Le dépassement de l’une ou l’autre de ces limites entraîne le retour du code d’erreur 429, accompagné d’une explication : error. Le budget d’exécution est délibérément restreint : une boucle incontrôlée envoyant des requêtes en temps réel à un prestataire de paiement constitue une défaillance bien plus grave qu’un script lent.

Les budgets sont attribués par clé, et non par boutique ; ainsi, une intégration ne peut pas épuiser le budget alloué à une autre.