REST API-referanse

Alle baner er relative til https://shopify.workflow-transactional-email.app. Alle endepunkter unntatt indeksen krever Authorization: Bearer fak_... - se Autentisering og API-nøkler.

Svarene er i JSON-format. Feilmeldingene har samme struktur gjennomgående:

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

Indeks og identitet

Metode	Sti	Nivå	Formål
HENT	/api/v1	ingen	API-indeks. Bekrefter at API-et er i drift og oppgir gjeldende versjon
HENT	/api/v1/me	les	Sjekk om en nøkkel fungerer, og se hvilket tilgangsnivå den har

Indeksen trenger ingen nøkkel, så det er en trygg helsesjekk å rette en monitor mot.

E-postoppsett

Metode	Sti	Nivå	Formål
HENT	/api/v1/email-templates	les	Viser oversikt over e-postmaler. q søker etter navn, emne og beskrivelse; category=transactional eller category=marketing viser én type e-post
INNLEGG	/api/v1/email-templates	skrive	Lag et oppsett
HENT	/api/v1/email-templates/:id	les	Én layout med design og vedlegg, bunntekstene og listen over språkene
PUT / PATCH	/api/v1/email-templates/:id	skrive	Endre et oppsett. Det er kun feltene du sender som endres
SLETT	/api/v1/email-templates/:id	skrive	Slett et oppsett sammen med oversettelsene og versjonene
HENT	/api/v1/layout-schema	les	Hvordan lage et oppsett: designformatet, standardinnstillingene for hver blokk, Liquid-koden du kan bruke, begrensninger og et eksempel

Listen godtar page (standard 1), limit (standard 25, maks. 100) og q, som søker etter navn, emne og beskrivelse. Det finnes ikke noe filter etter type via API-et; bruk i stedet category i hvert oppsett.

Et oppsett inneholder følgende felt:

Felt	Merknader
name, description	Navn er obligatorisk, maks. 200 tegn; beskrivelse maks. 2000
bodyType	visual (standard) eller text. Kan ikke endres etter at den er opprettet
defaultLocale	Språket i selve innholdet i oppsettet, en med mindre annet er angitt
category	transactional (standard) eller marketing. Se nedenfor
subject, previewText	Væske tillatt. Faget er obligatorisk
bodyDesign	Visuelle oppsett: { blocks, global?, header?, footer?, testVariables? }. Send det fullstendige designet når du endrer det; HTML-body-delen genereres ut fra dette
body	Tekstoppsett: HTML-body-delen
attachments	Tekstoppsett: [{ filename, fileKey, sendAsLink? }] for opplastede filer (se filene nedenfor) eller [{ filename, url }] for en fil som hentes via https når e-posten sendes
marketingTexts	Fottekstene i et markedsføringsoppsett, eller null. Se nedenfor

Liquid i emnet, forhåndsvisningsteksten, brødteksten og alle tekstblokker må analyseres, og hver fileKey må tilhøre nettbutikken din, ellers avvises skriveoperasjonen med en 400-feil som angir hvilket felt det gjelder. Les GET /api/v1/layout-schema før du oppretter et visuelt design: dette genereres av selve byggverktøyet, så det kan ikke endres.

Hver skriveoperasjon gjennom dette API-et lagres i layoutets versjonshistorikk, akkurat som når man lagrer i appen.

Oppsett for transaksjoner og markedsføring

category angir hva et oppsett er ment for. Et transaksjonsoppsett sendes til alle mottakere, uten endringer. Et markedsføringsoppsett hopper over mottakere som har meldt seg av (et trinn der «Til-mottakere som alle har meldt seg av» ikke sendes og vises som SKIPPED i historikken), sendes ut som én melding per «Til-mottaker» med sin egen avmeldingslenke (høyst 20 per trinn), og avsluttes med avmeldingssetningen og opplysningene om selskapet ditt. {{ unsubscribe_url }} og {{ unsubscribe_link }} lar deg plassere lenken selv; i transaksjonsmaler er begge tomme. Forhandlersiden av dette finnes i Markedsførings-e-poster og avmeldinger.

marketingTexts er teksten i bunnteksten som et markedsføringsoppsett bruker i stedet for de butikkfelles tekstene fra Innstillinger:

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

Alle feltene er valgfrie. Et angitt felt erstatter «Innstillinger»-teksten for det aktuelle feltet; de øvrige forblir uendret. null (standard) betyr «Innstillinger»-tekstene for e-postens språk. Begrensninger: unsubscribeText og companyDetails: 2000 tegn, unsubscribeLinkLabel: 100. Et unsubscribeText-felt må inneholde {{ unsubscribe_link }} eller {{ unsubscribe_url }}, ellers avvises innlegget. Feltet lagres for alle maler, men sendes kun med markedsføringsmaler.

Det er aldri mulig å forhindre at et oppsett slettes. Hvis det fortsatt finnes Shopify Flow-trinn som refererer til det, inneholder svaret en warning-melding som angir hvor mange; disse trinnene mislykkes inntil de bruker et annet oppsett.

Oversettelser

Metode	Sti	Nivå	Formål
HENT	/api/v1/email-templates/:id/translations	les	Hvert språk i et oppsett med tilhørende innhold
HENT	/api/v1/email-templates/:id/translations/:locale	les	Ett språk
PUT	/api/v1/email-templates/:id/translations/:locale	skrive	Opprett eller erstatt ett språk
SLETT	/api/v1/email-templates/:id/translations/:locale	skrive	Fjern ett språk. Da går systemet tilbake til standardoppsettet
INNLEGG	/api/v1/email-templates/:id/translations/:locale/promote	skrive	Angi dette språket som oppsettets hovedspråk

:locale er en språkkode, for eksempel de, fr eller pt-br; det spiller ingen rolle om det er store eller små bokstaver, og skilletegn har ingen betydning. Opptil 30 språk per oppsett. Feltet Språk i Shopify Flow-trinnet velger ett språk ved sending: den eksakte språkinnstillingen, deretter basisspråket, deretter en regional variant, ellers selve oppsettet.

En PUT-operasjon tar med seg hele det oversatte innholdet: subject (obligatorisk), previewText og bodyDesign (visuelt) eller body (tekst). Liquid-tagger og URL-er må forbli uendret. To felt er spesifikke for en oversettelse:

Felt	Tekstoppsett	Betydning
attachments	ja	En liste (med samme struktur som oppsettets) = vedleggene for dette språket, [] = ingen vedlegg på dette språket. null = send oppsettets vedlegg. Uten angivelse = behold det gjeldende valget; et nytt språk bruker oppsettets vedlegg. Visuelle oppsett har sine vedlegg som blokker i hvert språks bodyDesign-felt og avviser dette feltet
marketingTexts	noen	Fotnotetekstene for dette språket vises over layoutens, felt for felt. null = layoutens. Uten angivelse = behold det gjeldende valget

En oversettelse returneres med de samme to feltene: attachments er null, mens den sender oppsettets, og marketingTexts er null, mens den bruker oppsettets.

promote bytter om på oppsettet og oversettelsen: oppsettet overtar oversettelsens innhold og språkinnstilling, mens innholdet det tidligere hadde, blir oversettelsen for det språket det tidligere tilhørte. Vedlegg og bunntekster bytter også plass, slik at hvert språk fortsetter å sende det samme som før. Svaret rapporterer promoted, previousMainLanguage og oppsettet. Det er én versjon, så det kan angres.

Versjoner

Metode	Sti	Nivå	Formål
HENT	/api/v1/email-templates/:id/versions	les	Lagrede versjoner, med den nyeste først. Appen lagrer de 25 nyeste
HENT	/api/v1/email-templates/:id/versions/:version	les	Et fullstendig øyeblikksbilde av én versjon: oppsett og alle oversettelser
INNLEGG	/api/v1/email-templates/:id/versions/:version/restore	skrive	Sett den versjonen tilbake. Spilt inn som en ny versjon
HENT	/api/v1/email-templates/:id/versions/github?page=	les	Alle versjoner som er lagret i det tilknyttede GitHub-repositoriet, 20 per side
HENT	/api/v1/email-templates/:id/versions/github/:sha	les	Oppsettet slik det var ved en bestemt commit
INNLEGG	/api/v1/email-templates/:id/versions/github/:sha/restore	skrive	Gå tilbake til en tidligere GitHub-versjon - dette fungerer på samme måte som å lagre

GitHub-endepunktene returnerer feilkode 409 når det ikke er koblet til noe repository på utviklersiden. Se Versjonshistorikk for layout og Lagre ubegrenset layout-historikk på GitHub.

E-postavsendere

Metode	Sti	Nivå	Formål
HENT	/api/v1/smtp-configs	les	Vis SMTP-avsendere
HENT	/api/v1/senders	les	Vis en liste over tilknyttede postkasser (Microsoft 365, Google)

SMTP-avsendere oppgir hasUsername og hasPassword i stedet for selve påloggingsopplysningene - begge deler holdes tilbake, siden brukernavnet er like mye en del av påloggingsopplysningene som passordet. En avsender forblir identifiserbar gjennom navn, vert og avsenderadresse. Tilkoblede postkasser oppgir en delvis maskert adresse, for eksempel so***@example.com, og oppgir aldri sine påloggingstokener.

Skrivebeskyttet. Koble til og rediger avsendere i appen.

Hemmeligheter

Metode	Sti	Nivå	Formål
HENT	/api/v1/secrets	les	Oppgi hemmelige navn og beskrivelser

Returnerer hasValue, aldri selve verdien. Det finnes ingen API-endepunkt som henter en hemmelighet tilbake. Opprett og oppdater hemmeligheter i appen.

Lastede opp filer

Metode	Sti	Nivå	Formål
HENT	/api/v1/files	les	Liste over opplastede logoer, bilder og vedlegg
SLETT	/api/v1/files	skrive	Slett én, etter key-nøkkelen i brødteksten

List godtar page, limit (maks. 100) og q for å søke etter filnavn.

Legg til ?usage=true, så viser hver fil også inUse samt en usedBy-matrise som angir hvilke oppsett og forhåndsinnstillinger som refererer til den. Slik finner du alt du trygt kan slette i én enkelt forespørsel. Funksjonen skanner oppsettene og forhåndsinnstillingene dine, så den må aktiveres manuelt og er ikke standardinnstilt.

Det er ikke mulig å laste opp filer her - legg til filer via medievalgeren i appen.

HTTP-forespørsler

Metode	Sti	Nivå	Formål
HENT	/api/v1/http-requests	les	Vis HTTP-forespørsler
INNLEGG	/api/v1/http-requests	skrive	Opprett én
HENT	/api/v1/http-requests/:id	les	Kjøp en
PUT / PATCH	/api/v1/http-requests/:id	skrive	Oppdatering nr. 1
SLETT	/api/v1/http-requests/:id	skrive	Slett én
INNLEGG	/api/v1/http-requests/:id/test	utføre	Kjør den mot det virkelige målet

List godtar de samme parametrene page, limit og q som e-postmaler.

Mål-url-en må være http:// eller https://. Andre ordninger avvises når du lagrer.

Påskrevne påloggingsopplysninger i overskriften eller brødteksten blir skjult i hvert svar. Verdier som refereres til som {{ secrets.KEY }}, returneres slik de er skrevet, fordi selve referansen ikke er sensitiv.

Historie og statistikk

Omfatter både e-postutsendelser og HTTP-forespørsler.

Metode	Sti	Nivå	Formål
HENT	/api/v1/history	les	Liste over utførelser
HENT	/api/v1/history/:id	les	Hent én utførelse med forespørsels- og svardata
HENT	/api/v1/stats	les	Totaltall og suksessrate

Historikken støtter page, limit (maks. 100), actionType, status (PENDING, SUCCESS, FAILED, SKIPPED) og actionConfigId for å filtrere etter en enkelt layout eller forespørsel.

SKIPPED er en markedsførings-e-post der alle mottakerne hadde meldt seg av: det ble ikke sendt noe, ingen kvote ble brukt, og den teller ikke med i suksessraten.

actionType må være nøyaktig EMAIL eller HTTP_REQUEST. En ukjent verdi blir ignorert i stedet for å bli avvist, så en skrivefeil fører til at alt returneres i stedet for at det oppstår en feil.

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

Statuskoder

Kode	Betydning
200	Suksess
201	Opprettet
400	Feilaktig forespørsel eller mislykket validering. error-parameteren angir feltet, for eksempel subject: required
401	Manglende, feilformet eller tilbakekalt API-nøkkel
403	Nøkkelen er gyldig, men sikkerhetsnivået er for lavt for dette endepunktet
404	Ikke funnet, eller tilhører en annen butikk
405	Feil metode for denne banen
409	Avvist fordi posten fortsatt er i bruk (sletting av fil), eller fordi GitHub ikke er tilkoblet (GitHub-versjoner)
429	Hastighetsbegrenset - se nedenfor
502	Forespørselen ble kjørt, men tredjepartsmålet mislyktes

En post som tilhører en annen butikk returnerer 404 i stedet for 403, så API-et bekrefter aldri at en ID finnes et annet sted.

Ratebegrensninger

To uavhengige budsjetter, begge per nøkkel:

• 300 forespørsler per 60 sekunder på tvers av alle endepunkter.
• I tillegg 60 utførte anrop per time, som omfatter POST /api/v1/http-requests/:id/test.

Hvis noen av disse verdiene overskrides, returneres feilkoden 429 sammen med en forklarende error-melding. Utførelsesbudsjettet er bevisst satt lavt: En løkke som går amok og sender for mange forespørsler til en betalingsleverandør, er en langt alvorligere feil enn et skript som kjører tregt.

Budsjettene gjelder per nøkkel, ikke per butikk, så én integrasjon kan ikke tømme kvoten til en annen.