REST API-reference

Alle stier er relative i forhold til https://shopify.workflow-transactional-email.app. Alle endpunkter undtagen indekset kræver Authorization: Bearer fak_... - se Godkendelse og API-nøgler.

Svarene er i JSON-format. Fejlmeddelelserne har samme struktur i alle tilfælde:

json

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

Indeks og identitet

Metode	Sti	Niveau	Formål
HENT	`/api/v1`	ingen	API-indeks. Bekræfter, at API’et er oppe, og angiver den aktuelle version
HENT	`/api/v1/me`	læs	Kontroller, om en nøgle fungerer, og se, hvilket adgangsniveau den har

Indekset kræver ingen nøgle, så det er en sikker måde at foretage en sundhedstjek på.

E-mail-layouter

Metode	Sti	Niveau	Formål
HENT	`/api/v1/email-templates`	læs	Oversigt over e-mail-layouts. `q` søger på navn, emne og beskrivelse; `category=transactional` eller `category=marketing` viser en bestemt e-mail-type
INDLÆG	`/api/v1/email-templates`	skrive	Opret et layout
HENT	`/api/v1/email-templates/:id`	læs	Et layout med dets design eller vedhæftede filer, dets fodtekster og listen over de sprog, det findes på
PUT / PATCH	`/api/v1/email-templates/:id`	skrive	Rediger et layout. Det er kun de felter, du sender, der ændres
SLET	`/api/v1/email-templates/:id`	skrive	Slet et layout sammen med dets oversættelser og versioner
HENT	`/api/v1/layout-schema`	læs	Sådan skriver du et layout: designformatet, standardindstillingerne for hver blok, den Liquid-kode, du kan bruge, begrænsninger og et eksempel

Listen accepterer page (standard 1), limit (standard 25, maks. 100) og q, som søger på navn, emne og beskrivelse. Der er ingen filtrering efter type via API’et; læs i stedet category for hvert layout.

Et layout indeholder følgende felter:

Felt	Noter
`name`, `description`	Navn er obligatorisk, højst 200 tegn; beskrivelse højst 2000
`bodyType`	`visual` (standard) eller `text`. Kan ikke ændres, når den først er oprettet
`defaultLocale`	Sproget i layoutets eget indhold, `en`, medmindre andet er angivet
`category`	`transactional` (standard) eller `marketing`. Se nedenfor
`subject`, `previewText`	Væske er tilladt. Faget er obligatorisk
`bodyDesign`	Visuelle layout: `{ blocks, global?, header?, footer?, testVariables? }`. Send det færdige design, når du ændrer det; HTML-filen `body` genereres ud fra det
`body`	Tekstlayout: HTML-body-elementet
`attachments`	Tekstformater: `[{ filename, fileKey, sendAsLink? }]` for uploadede filer (se filerne nedenfor) eller `[{ filename, url }]` for en fil, der hentes via https, når e-mailen sendes
`marketingTexts`	Fodteksterne i et markedsføringslayout, eller `null`. Se nedenfor

Liquid-kode i emnefeltet, forhåndsvisningsteksten, brødteksten og alle tekstblokke skal være gyldig, og alle fileKey skal henvise til din butik, ellers afvises indlægget med en 400-fejl, der angiver det pågældende felt. Læs GET /api/v1/layout-schema, inden du udarbejder et visuelt design: Det genereres af selve builderen, så det kan ikke afvige.

Hver eneste skrivning via denne API gemmes i layoutets versionshistorik, præcis som når man gemmer i appen.

Layout til transaktioner og markedsføring

category beskriver, hvad et layout bruges til. Et transaktionslayout sendes uændret til alle modtagere. Et marketinglayout springer modtagere over, der har afmeldt sig (et trin, hvor »To recipients all unsubscribed« ikke sendes og vises som »SKIPPED« i historikken), sendes ud som én besked pr. »To«-modtager med sit eget afmeldingslink (højst 20 pr. trin) og afsluttes med afmeldingssætningen og dine virksomhedsoplysninger. {{ unsubscribe_url }} og {{ unsubscribe_link }} - indsæt linket selv; i transaktionslayouter er begge felter tomme. Oplysningerne for forhandlere findes på Markedsførings-e-mails og afmeldinger.

marketingTexts Er teksten i sidefoden den, som et marketinglayout bruger i stedet for de butiksdækkende tekster fra Indstillinger:

json

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

Alle felter er valgfrie. Et udfyldt felt erstatter »Indstillinger«-teksten for det pågældende felt; de øvrige forbliver uændrede. »null« (standardindstillingen) betyder, at »Indstillinger«-teksterne vises på e-mailens sprog. Begrænsninger: »unsubscribeText« og »companyDetails« er begrænset til 2000 tegn, mens »unsubscribeLinkLabel« er begrænset til 100 tegn. En unsubscribeText skal indeholde {{ unsubscribe_link }} eller {{ unsubscribe_url }}, ellers afvises indtastningen. Feltet gemmes for alle layouttyper, men sendes kun med marketinglayout.

Sletning af et layout blokeres aldrig. Hvis der stadig er trin i Shopify Flow, der henviser til det, indeholder svaret en warning, der angiver antallet; disse trin mislykkes, indtil der anvendes et andet layout.

Oversættelser

Metode	Sti	Niveau	Formål
HENT	`/api/v1/email-templates/:id/translations`	læs	Hvert sprog i et layout med dets indhold
HENT	`/api/v1/email-templates/:id/translations/:locale`	læs	Ét sprog
PUT	`/api/v1/email-templates/:id/translations/:locale`	skrive	Opret eller erstat et sprog
SLET	`/api/v1/email-templates/:id/translations/:locale`	skrive	Fjern et sprog. Siderne skifter i så fald tilbage til standardlayoutet
INDLÆG	`/api/v1/email-templates/:id/translations/:locale/promote`	skrive	Gør dette sprog til layoutets hovedsprog

:locale er en sprogkode, f.eks. de, fr eller pt-br; store og små bogstaver samt separator spiller ingen rolle. Op til 30 sprog pr. layout. Feltet »Sprog« i trinnet »Shopify Flow« vælger et sprog ved afsendelse: den nøjagtige lokalitet, derefter basissproget, derefter en regional variant, ellers selve layoutet.

En oversættelsesfil (PUT) indeholder det fulde oversatte indhold: subject (påkrævet), previewText og bodyDesign (visuelt) eller body (tekst). Liquid-tags og URL’er skal forblive uændrede. To felter er specifikke for en oversættelse:

Felt	Tekstlayouter	Betydning
`attachments`	ja	En liste (samme form som layoutets) = dette sprogs egne vedhæftede filer, `[]` = ingen på dette sprog. `null` = send layoutets vedhæftede filer. Udeladt = behold det nuværende valg; et nyt sprog bruger layoutets. Visuelle layouts medbringer deres vedhæftede filer som blokke i hvert sprogs `bodyDesign` og afviser dette felt
`marketingTexts`	enhver	Dette sprogs fodtekster vises oven på layoutets, felt for felt. `null` = layoutets. Udeladt = behold det nuværende valg

Der returneres en oversættelse med de samme to felter: attachments er null, mens den bruger layoutets, og marketingTexts er null, mens den bruger layoutets.

promote bytter om på layoutet og oversættelsen: layoutet overtager oversættelsens indhold og sprogindstilling, og det indhold, det tidligere havde, bliver nu oversættelsen til det sprog, det tidligere var på. Vedhæftede filer og fodtekster bytter også plads, så hvert sprog fortsætter med at sende det, det sendte før. Svaret angiver promoted, previousMainLanguage og layoutet. Det er én version, så det kan fortrydes.

Versioner

Metode	Sti	Niveau	Formål
HENT	`/api/v1/email-templates/:id/versions`	læs	Gemte versioner, med den nyeste først. Appen gemmer de 25 nyeste
HENT	`/api/v1/email-templates/:id/versions/:version`	læs	Det komplette øjebliksbillede af en version: layout og alle oversættelser
INDLÆG	`/api/v1/email-templates/:id/versions/:version/restore`	skrive	Sæt den version tilbage. Indspillet som en ny version
HENT	`/api/v1/email-templates/:id/versions/github?page=`	læs	Alle versioner, der er gemt i det tilknyttede GitHub-repository, 20 pr. side
HENT	`/api/v1/email-templates/:id/versions/github/:sha`	læs	Layoutet, som det så ud ved en bestemt commit
INDLÆG	`/api/v1/email-templates/:id/versions/github/:sha/restore`	skrive	Gendan en GitHub-version - det fungerer ligesom at gemme

GitHub-endpunkterne returnerer fejlkode 409, når der ikke er tilknyttet noget repository på udviklersiden. Se Historik over layoutversioner og Gem ubegrænset layout-historik på GitHub.

E-mail-afsendere

Metode	Sti	Niveau	Formål
HENT	`/api/v1/smtp-configs`	læs	Vis SMTP-afsendere
HENT	`/api/v1/senders`	læs	Vis en liste over tilknyttede postkasser (Microsoft 365, Google)

SMTP-afsendere angiver hasUsername og hasPassword i stedet for selve adgangsoplysningerne - begge dele skjules, da et brugernavn er lige så meget en del af adgangsoplysningerne som adgangskoden. En afsender kan stadig identificeres ved sit navn, sin vært og sin afsenderadresse. Tilsluttede postkasser angiver en delvist skjult adresse, f.eks. so***@example.com, og aldrig deres log-in-tokens.

Skrivebeskyttet. Opret forbindelse til og rediger afsendere i appen.

Hemmeligheder

Metode	Sti	Niveau	Formål
HENT	`/api/v1/secrets`	læs	Oplist hemmelige navne og beskrivelser

Returnerer hasValue, aldrig selve værdien. Der findes ingen endpoint, der henter en hemmelighed tilbage. Opret og opdater hemmeligheder i appen.

Uploaded filer

Metode	Sti	Niveau	Formål
HENT	`/api/v1/files`	læs	Liste over uploadede logoer, billeder og vedhæftede filer
SLET	`/api/v1/files`	skrive	Slet én, af `key` i brødteksten

Listen accepterer page, limit (maks. 100) og q til søgning efter filnavn.

Tilføj ?usage=true, og hver fil viser desuden inUse samt en usedBy-tabel med navnene på de layouts og forudindstillinger, der henviser til den. På den måde kan du med en enkelt forespørgsel finde alt, hvad der sikkert kan slettes. Funktionen scanner dine layouts og forudindstillinger, så den er kun aktiveret, hvis du vælger det - det er ikke standardindstillingen.

Der er ikke mulighed for at uploade her - tilføj filer via medievalg i appen.

Det er bevidst ikke muligt at slette en fil, der er i brug

DELETE /api/v1/files returnerer 409, hvis der stadig er e-mail-layouts eller forudindstillede sidehoveder/sidefødder, der henviser til filen, og svaret angiver dem i usedBy.

Den samme upload kan genbruges i så mange layouts, som du ønsker, så hvis du sletter en, der stadig henvises til, vil det medføre, at en anden e-mail, der stadig sendes ud til kunderne, ikke fungerer. Fjern filen fra de layouts, der er nævnt i svaret, og slet den derefter.

{ "key": "uploads/your-shop.myshopify.com/abc123.png" }

Filer, som der ikke henvises til nogen steder, skal slettes med det samme.

HTTP-anmodninger

Metode	Sti	Niveau	Formål
HENT	`/api/v1/http-requests`	læs	Vis HTTP-anmodninger
INDLÆG	`/api/v1/http-requests`	skrive	Opret en
HENT	`/api/v1/http-requests/:id`	læs	Køb en
PUT / PATCH	`/api/v1/http-requests/:id`	skrive	Opdatering 1
SLET	`/api/v1/http-requests/:id`	skrive	Slet én
INDLÆG	`/api/v1/http-requests/:id/test`	udføre	Kør det mod det egentlige mål

Listen accepterer de samme parametre - page, limit og q - som e-mail-layouts.

Mål-urlen skal være http:// eller https://. Andre domæneformater afvises, når du gemmer.

Bogstavelige legitimationsoplysninger, der er indskrevet i en header eller i brødteksten, maskeres i hvert svar. Værdier, der henvises til som »{{ secrets.KEY }}«, returneres som angivet, da selve henvisningen ikke er følsom.

Historie og statistik

Omfatter både e-mail-udsendelser og HTTP-anmodninger.

Metode	Sti	Niveau	Formål
HENT	`/api/v1/history`	læs	Vis udførelser
HENT	`/api/v1/history/:id`	læs	Hent én udførelse med anmodnings- og svardata
HENT	`/api/v1/stats`	læs	Samlede tal og succesrate

I »History« accepteres page, limit (maks. 100), actionType, status (PENDING, SUCCESS, FAILED, SKIPPED) samt actionConfigId til at filtrere efter et enkelt layout eller en enkelt anmodning.

SKIPPED er en markedsførings-e-mail, hvor alle modtagerne havde afmeldt sig: der blev ikke sendt noget, der blev ikke brugt nogen kvote, og den tæller ikke med i succesraten.

actionType skal være præcis EMAIL eller HTTP_REQUEST. En ukendt værdi ignoreres i stedet for at blive afvist, så en stavefejl returnerer alle resultater i stedet for at give en fejlmeddelelse.

Stats accepterer days (standard 30, maks. 365).

Statuskoder

Kode	Betydning
200	Succes
201	Oprettet
400	Fejl i anmodningen eller mislykket validering. I `error` angives feltnavnet, f.eks. `subject: required`
401	Manglende, fejlformateret eller tilbagekaldt API-nøgle
403	Nøglen er gyldig, men dens sikkerhedsniveau er for lavt til dette endpoint
404	Ikke fundet, eller tilhører en anden butik
405	Forkert metode til denne sti
409	Afvist, fordi posten stadig er i brug (sletning af fil), eller fordi GitHub ikke er forbundet (GitHub-versioner)
429	Hastighedsbegrænset - se nedenfor
502	Anmodningen blev udført, men tredjepartsmålet mislykkedes

En post, der tilhører en anden butik, returnerer en 404-fejl i stedet for en 403, så API’et bekræfter aldrig, at et id findes et andet sted.

Hastighedsbegrænsninger

To uafhængige budgetter, begge pr. nøgle:

300 anmodninger pr. 60 sekunder på tværs af alle endpoints.
Derudover foretages der 60 opkald i timen, der dækker området POST /api/v1/http-requests/:id/test.

Hvis en af disse grænser overskrides, returneres fejlkode 429 med en forklarende besked: »error«. Budgettet for udførelse er bevidst stramt: En løbsk løkke, der sender live-anmodninger til en betalingsudbyder, er en langt alvorligere fejl end et langsomt script.

Budgetterne er pr. nøgle, ikke pr. butik, så én integration kan ikke opbruge en anden integrations budget.