REST API-referentie

Alle paden zijn relatief ten opzichte van https://shopify.workflow-transactional-email.app. Voor elk eindpunt, met uitzondering van de index, is Authorization: Bearer fak_... vereist - zie Authenticatie en API-sleutels.

De antwoorden zijn in JSON-formaat. Foutmeldingen hebben overal dezelfde structuur:

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

Index en identiteit

Methode	Pad	Niveau	Doel
GET	/api/v1	geen	API-index. Bevestigt dat de API actief is en geeft de huidige versie weer
GET	/api/v1/me	lezen	Controleer of een sleutel werkt en bekijk het toegangsniveau ervan

De index heeft geen sleutel nodig; het is dus een veilige manier om de status te controleren.

E-mailopmaak

Methode	Pad	Niveau	Doel
GET	/api/v1/email-templates	lezen	Overzicht van e-mailindelingen. q zoekt op naam, onderwerp en beschrijving; category=transactional of category=marketing geeft een overzicht van één type e-mail
BERICHT	/api/v1/email-templates	schrijven	Een lay-out maken
GET	/api/v1/email-templates/:id	lezen	Eén lay-out met het ontwerp of de bijlagen, de voetteksten en de lijst met talen
PUT / PATCH	/api/v1/email-templates/:id	schrijven	Een lay-out wijzigen. Alleen de velden die u doorgeeft, worden gewijzigd
VERWIJDEREN	/api/v1/email-templates/:id	schrijven	Een lay-out met de bijbehorende vertalingen en versies verwijderen
GET	/api/v1/layout-schema	lezen	Hoe schrijft u een lay-out: het ontwerpformaat, de standaardinstellingen van elk blok, de Liquid-code die u kunt gebruiken, beperkingen en een voorbeeld

De lijst accepteert page (standaard 1), limit (standaard 25, max. 100) en q, waarmee op naam, onderwerp en beschrijving wordt gezocht. Via de API is er geen filter op type beschikbaar; raadpleeg in plaats daarvan category voor elke lay-out.

Een lay-out bevat de volgende velden:

Veld	Opmerkingen
name, description	Naam verplicht, maximaal 200 tekens; beschrijving maximaal 2000
bodyType	visual (standaard) of text. Wordt na aanmaak vastgelegd
defaultLocale	De taal van de eigen inhoud van de lay-out, en, tenzij anders ingesteld
category	transactional (standaard) of marketing. Zie hieronder
subject, previewText	Vloeistoffen zijn toegestaan. Dit is een verplicht vak.
bodyDesign	Visuele lay-outs: { blocks, global?, header?, footer?, testVariables? }. Stuur het volledige ontwerp mee wanneer u wijzigingen aanbrengt; de HTML-body wordt hieruit gegenereerd
body	Tekstopmaak: de HTML-body
attachments	Tekstopmaak: [{ filename, fileKey, sendAsLink? }] voor geüploade bestanden (zie onderstaande bestanden) of [{ filename, url }] voor een bestand dat via https wordt opgehaald op het moment dat de e-mail wordt verzonden
marketingTexts	De voetteksten van een marketinglay-out, oftewel null. Zie hieronder

De tekst in het onderwerp, de previewtekst, de hoofdtekst en elke tekstblok moet correct worden geparseerd, en elke fileKey moet bij uw winkel horen; anders wordt het schrijven geweigerd met een 400-foutcode waarin het betreffende veld wordt vermeld. Lees GET /api/v1/layout-schema voordat u een visueel ontwerp opstelt: dit wordt door de builder zelf gegenereerd en kan dus niet afwijken.

Elke schrijfbewerking via deze API wordt opgenomen in de versiegeschiedenis van de lay-out, net zoals bij het opslaan in de app.

Lay-outs voor transacties en marketing

category beschrijft waarvoor een lay-out dient. Een transactionele lay-out wordt ongewijzigd naar elke ontvanger verzonden. Een marketinglay-out slaat ontvangers over die zich hebben afgemeld (een stap waarbij de lijst ‘To recipients all unsubscribed’ niet wordt verzonden en in de geschiedenis wordt weergegeven als SKIPPED), wordt verzonden als één bericht per ‘To’-ontvanger met een eigen afmeldlink (maximaal 20 per stap) en eindigt met de afmeldzin en uw bedrijfsgegevens. {{ unsubscribe_url }} en {{ unsubscribe_link }}: plaats de link zelf; in transactionele lay-outs zijn beide velden leeg. De informatie voor merchants hierover vindt u op Marketingmails en afmeldingen.

marketingTexts Is de tekst in de voettekst een marketinglay-out die wordt gebruikt in plaats van de winkelbrede teksten uit de instellingen:

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

Elk veld is optioneel. Een ingevuld veld vervangt de tekst in de instellingen voor dat veld; de overige velden blijven ongewijzigd. null (de standaardinstelling) betekent dat de teksten in de instellingen worden weergegeven in de taal van de e-mail. Limieten: unsubscribeText en companyDetails 2000 tekens, unsubscribeLinkLabel 100. Een unsubscribeText moet {{ unsubscribe_link }} of {{ unsubscribe_url }} bevatten, anders wordt het schrijven geweigerd. Het veld wordt voor elke lay-out opgeslagen, maar alleen met marketinglay-outs verzonden.

Het verwijderen van een lay-out wordt nooit geblokkeerd. Indien stappen in Shopify Flow nog steeds naar deze lay-out verwijzen, bevat het antwoord een warning waarin wordt aangegeven om hoeveel stappen het gaat; deze stappen mislukken totdat er een andere lay-out wordt gebruikt.

Vertalingen

Methode	Pad	Niveau	Doel
GET	/api/v1/email-templates/:id/translations	lezen	Elke taal van een lay-out met de bijbehorende inhoud
GET	/api/v1/email-templates/:id/translations/:locale	lezen	Eén taal
PUT	/api/v1/email-templates/:id/translations/:locale	schrijven	Eén taal aanmaken of vervangen
VERWIJDEREN	/api/v1/email-templates/:id/translations/:locale	schrijven	Verwijder één taal. In dat geval wordt teruggevallen op de standaardindeling
BERICHT	/api/v1/email-templates/:id/translations/:locale/promote	schrijven	Stel die taal in als de hoofdtaal van de lay-out

:locale is een taalcode zoals de, fr of pt-br; hoofdletters en scheidingstekens spelen geen rol. Maximaal 30 talen per lay-out. Het veld ‘Taal’ in de stap Shopify Flow kiest er op het moment van verzending één uit: de exacte locale, vervolgens de basistaal, daarna een regionale variant, of anders de lay-out zelf.

Een PUT bevat de volledige vertaalde inhoud: subject (verplicht), previewText en bodyDesign (afbeelding) of body (tekst). Laat Liquid-tags en URL’s ongewijzigd. Twee velden zijn specifiek voor een vertaling:

Veld	Tekstopmaak	Betekenis
attachments	ja	Een lijst (met dezelfde indeling als die van de lay-out) = de bijlagen van deze taal zelf, [] = geen bijlagen in deze taal. null = de bijlagen van de lay-out verzenden. Weggelaten = de huidige keuze behouden; een nieuwe taal gebruikt die van de lay-out. Visuele lay-outs vervoeren hun bijlagen als blokken in het bestand bodyDesign van elke taal en negeren dit veld
marketingTexts	welke dan ook	De voetteksten van deze taal worden veld voor veld boven die van de lay-out weergegeven. null = die van de lay-out. Weggelaten = de huidige keuze behouden

Er wordt een vertaling teruggegeven met dezelfde twee velden: attachments is null terwijl de lay-out wordt meegestuurd, en marketingTexts is null terwijl de lay-out wordt gebruikt.

promote wisselt de lay-out en de vertaling om: de lay-out neemt de inhoud en de taalinstelling van de vertaling over, en de inhoud die de lay-out zelf had, wordt de vertaling voor de taal waarin deze voorheen was opgenomen. Bijlagen en voettekstteksten wisselen eveneens van plaats, zodat elke taal blijft verzenden wat zij eerder verzond. Het antwoord vermeldt promoted, previousMainLanguage en de lay-out. Het betreft één versie, zodat deze ongedaan kan worden gemaakt.

Versies

Methode	Pad	Niveau	Doel
GET	/api/v1/email-templates/:id/versions	lezen	Opgeslagen versies, met de nieuwste bovenaan. De app bewaart de 25 nieuwste versies
GET	/api/v1/email-templates/:id/versions/:version	lezen	Het volledige overzicht van één versie: lay-out en alle vertalingen
BERICHT	/api/v1/email-templates/:id/versions/:version/restore	schrijven	Zet die versie er weer op. Opgenomen als een nieuwe versie
GET	/api/v1/email-templates/:id/versions/github?page=	lezen	Elke versie die in de gekoppelde GitHub-repository wordt bewaard, 20 per pagina
GET	/api/v1/email-templates/:id/versions/github/:sha	lezen	De lay-out zoals deze bij een bepaalde commit was
BERICHT	/api/v1/email-templates/:id/versions/github/:sha/restore	schrijven	Een GitHub-versie terugzetten, net als bij het opslaan

De GitHub-eindpunten geven een 409-foutmelding terug wanneer er op de ontwikkelaarspagina geen repository is gekoppeld. Zie Versiegeschiedenis van de lay-out en Bewaar een onbeperkte geschiedenis van lay-outs op GitHub.

Afzenders van e-mails

Methode	Pad	Niveau	Doel
GET	/api/v1/smtp-configs	lezen	Lijst met SMTP-afzenders
GET	/api/v1/senders	lezen	Een overzicht weergeven van gekoppelde mailboxen (Microsoft 365, Google)

SMTP-afzenders vermelden hasUsername en hasPassword in plaats van de inloggegevens zelf - beide delen worden achtergehouden, aangezien een gebruikersnaam net zo goed deel uitmaakt van de inloggegevens als het wachtwoord. Een afzender blijft herkenbaar aan de hand van zijn naam, host en afzenderadres. Gekoppelde mailboxen vermelden een gedeeltelijk gemaskeerd adres, zoals so***@example.com, en nooit hun inlogtokens.

Alleen-lezen. U kunt afzenders koppelen en bewerken in de app.

Geheimen

Methode	Pad	Niveau	Doel
GET	/api/v1/secrets	lezen	Geef een overzicht van de geheime namen en beschrijvingen

Geeft altijd hasValue terug, nooit de waarde zelf. Er is geen eindpunt waarmee een geheim kan worden opgehaald. Maak geheimen aan en werk ze bij in de app.

Geüploade bestanden

Methode	Pad	Niveau	Doel
GET	/api/v1/files	lezen	Lijst met geüploade logo’s, afbeeldingen en bijlagen
VERWIJDEREN	/api/v1/files	schrijven	Verwijder één exemplaar, van key in de hoofdtekst

De lijst accepteert page, limit (max. 100) en q om op bestandsnaam te zoeken.

Voeg ?usage=true toe; elk bestand bevat dan ook de vermelding inUse, plus een usedBy-array met de namen van de lay-outs en presets die ernaar verwijzen. Op die manier kunt u in één verzoek alles vinden wat veilig kan worden verwijderd. Het scant uw lay-outs en presets, dus het is een opt-in-functie en niet de standaardinstelling.

Het uploaden is hier niet beschikbaar - voeg bestanden toe via de mediakiezer in de app.

HTTP-verzoeken

Methode	Pad	Niveau	Doel
GET	/api/v1/http-requests	lezen	HTTP-verzoeken weergeven
BERICHT	/api/v1/http-requests	schrijven	Maak er één aan
GET	/api/v1/http-requests/:id	lezen	Koop er één
PUT / PATCH	/api/v1/http-requests/:id	schrijven	Update 1
VERWIJDEREN	/api/v1/http-requests/:id	schrijven	Verwijder er één
BERICHT	/api/v1/http-requests/:id/test	uitvoeren	Voer het uit op het daadwerkelijke doel

List accepteert dezelfde parameters page, limit en q als e-mailopmaak.

Het doel-url-adres moet http:// of https:// zijn. Andere schema’s worden bij het opslaan geweigerd.

Inloggegevens die letterlijk in de header of de body zijn opgenomen, worden in elk antwoord gemaskeerd. Waarden waarnaar wordt verwezen als {{ secrets.KEY }} worden ongewijzigd weergegeven, aangezien de verwijzing zelf niet gevoelig is.

Geschiedenis en statistieken

Dit geldt zowel voor het verzenden van e-mails als voor HTTP-verzoeken.

Methode	Pad	Niveau	Doel
GET	/api/v1/history	lezen	Lijsten uitvoeren
GET	/api/v1/history/:id	lezen	Verkrijg één uitvoering met verzoek- en antwoordgegevens
GET	/api/v1/stats	lezen	Totalen en slagingspercentage

History accepteert page, limit (max. 100), actionType, status (PENDING, SUCCESS, FAILED, SKIPPED) en actionConfigId om te filteren op één bepaalde lay-out of één verzoek.

SKIPPED is een marketing-e-mail waarvan alle ontvangers zich hadden afgemeld: er is niets verzonden, er is geen quotum verbruikt en deze e-mail telt niet mee voor het succespercentage.

actionType moet precies EMAIL of HTTP_REQUEST zijn. Een onbekende waarde wordt genegeerd in plaats van afgewezen, zodat een typefout alle resultaten weergeeft in plaats van een foutmelding te geven.

Stats accepteert een waarde van days (standaard 30, maximaal 365).

Statuscodes

Code	Betekenis
200	Succes
201	Aangemaakt
400	Onjuist opgebouwd verzoek of mislukte validatie. In de error wordt het veld vermeld, bijvoorbeeld subject: required
401	Ontbrekende, onjuist opgebouwde of ingetrokken API-sleutel
403	De sleutel is geldig, maar het beveiligingsniveau is te laag voor dit eindpunt
404	Niet gevonden, of het product is afkomstig uit een andere winkel
405	Onjuiste methode voor dit pad
409	Afgewezen omdat het record nog in gebruik is (verwijderen van bestanden), of omdat er geen verbinding is met GitHub (GitHub-versies)
429	Beperkt aantal beschikbaar - zie hieronder
502	Het verzoek is uitgevoerd, maar het doel van de derde partij is mislukt

Een record dat bij een andere winkel hoort, levert een 404-foutcode op in plaats van een 403, waardoor de API nooit bevestigt dat een id elders bestaat.

Verwerkingslimieten

Twee afzonderlijke begrotingen, beide per sleutel:

• 300 verzoeken per 60 seconden voor alle eindpunten.
• Daarnaast worden er 60 oproepen per uur afgehandeld, met betrekking tot POST /api/v1/http-requests/:id/test.

Als een van beide wordt overschreden, wordt de foutcode 429 geretourneerd, vergezeld van de toelichting error. Het uitvoeringsbudget is bewust krap gehouden: een uit de hand gelopen lus die live-verzoeken naar een betalingsprovider verstuurt, is een veel ernstigere storing dan een traag script.

Budgetten worden per sleutel berekend, niet per winkel, zodat de toewijzing van de ene integratie niet ten koste gaat van die van een andere.