REST-API-Referenz
Alle Pfade sind relativ zu https://shopify.workflow-transactional-email.app. Jeder Endpunkt außer dem Index benötigt Authorization: Bearer fak_... - siehe Authentifizierung und API-Schlüssel.
Antworten sind im JSON-Format. Fehler haben durchgängig dieselbe Struktur:
{ "error": "Invalid or missing API key" }Index und Identität
| Methode | Pfad | Level | Zweck |
|---|---|---|---|
| GET | /api/v1 |
none | API-Index. Bestätigt, dass die API läuft, und meldet die aktuelle Version |
| GET | /api/v1/me |
read | Prüft, ob ein Schlüssel funktioniert, und zeigt dessen Zugriffsebene |
Der Index benötigt keinen Schlüssel und ist daher ein sicherer Health-Check, den ein Monitor ansprechen kann.
E-Mail-Layouts
| Methode | Pfad | Level | Zweck |
|---|---|---|---|
| GET | /api/v1/email-templates |
read | E-Mail-Layouts auflisten |
| GET | /api/v1/email-templates/:id |
read | Ein Layout abrufen, einschließlich Betreff, Vorschautext und gerendertem Inhalt |
Akzeptiert page (Standard 1), limit (Standard 25, maximal 100) und q zur Suche nach Namen.
Nur lesbar. Layouts werden in der App erstellt und bearbeitet.
E-Mail-Absender
| Methode | Pfad | Level | Zweck |
|---|---|---|---|
| GET | /api/v1/smtp-configs |
read | SMTP-Absender auflisten |
| GET | /api/v1/senders |
read | Verbundene Postfächer auflisten (Microsoft 365, Google) |
SMTP-Absender melden hasUsername und hasPassword statt der eigentlichen Zugangsdaten - beide Hälften werden zurückgehalten, da ein Benutzername genauso Teil der Zugangsdaten ist wie das Passwort. Ein Absender bleibt anhand seines Namens, Hosts und der Absenderadresse identifizierbar. Verbundene Postfächer melden eine teilweise maskierte Adresse wie so***@example.com und niemals ihre Anmeldetoken.
Nur lesbar. Absender werden in der App verbunden und bearbeitet.
Secrets
| Methode | Pfad | Level | Zweck |
|---|---|---|---|
| GET | /api/v1/secrets |
read | Namen und Beschreibungen von Secrets auflisten |
Liefert hasValue, niemals den Wert selbst. Es gibt keinen Endpunkt, der ein Secret zurückliest. Secrets werden in der App erstellt und aktualisiert.
Hochgeladene Dateien
| Methode | Pfad | Level | Zweck |
|---|---|---|---|
| GET | /api/v1/files |
read | Hochgeladene Logos, Bilder und Anhänge auflisten |
| DELETE | /api/v1/files |
write | Eine Datei löschen, per key im Body |
Die Liste akzeptiert page, limit (maximal 100) und q zur Suche nach Dateinamen.
Mit ?usage=true meldet jede Datei zusätzlich inUse sowie ein usedBy-Array, das die referenzierenden Layouts und Presets benennt. So finden Sie in einer einzigen Anfrage alles, was sich gefahrlos entfernen lässt. Dabei werden Ihre Layouts und Presets durchsucht, weshalb dies optional und nicht die Standardeinstellung ist.
Das Hochladen ist hier nicht verfügbar - fügen Sie Dateien über die Medienauswahl in der App hinzu.
HTTP-Anfragen
| Methode | Pfad | Level | Zweck |
|---|---|---|---|
| GET | /api/v1/http-requests |
read | HTTP-Anfragen auflisten |
| POST | /api/v1/http-requests |
write | Eine neue erstellen |
| GET | /api/v1/http-requests/:id |
read | Eine abrufen |
| PUT / PATCH | /api/v1/http-requests/:id |
write | Eine aktualisieren |
| DELETE | /api/v1/http-requests/:id |
write | Eine löschen |
| POST | /api/v1/http-requests/:id/test |
execute | Gegen das echte Ziel ausführen |
Die Liste akzeptiert dieselben Parameter page, limit und q wie bei E-Mail-Layouts.
Die Ziel-url muss mit http:// oder https:// beginnen. Andere Schemata werden beim Speichern abgelehnt.
Zugangsdaten, die als Literal in einen Header oder Body geschrieben wurden, werden in jeder Antwort maskiert. Werte, die als {{ secrets.KEY }} referenziert werden, werden unverändert zurückgegeben, da die Referenz selbst nicht sensibel ist.
Verlauf und Statistiken
Umfasst sowohl E-Mail-Versendungen als auch HTTP-Anfragen.
| Methode | Pfad | Level | Zweck |
|---|---|---|---|
| GET | /api/v1/history |
read | Ausführungen auflisten |
| GET | /api/v1/history/:id |
read | Eine Ausführung mit Anfrage- und Antwortdaten abrufen |
| GET | /api/v1/stats |
read | Gesamtzahlen und Erfolgsquote |
Der Verlauf akzeptiert page, limit (maximal 100), actionType, status (PENDING, SUCCESS, FAILED) sowie actionConfigId, um nach einem einzelnen Layout oder einer einzelnen Anfrage zu filtern.
actionType muss genau EMAIL oder HTTP_REQUEST lauten. Ein nicht erkannter Wert wird ignoriert statt abgelehnt, sodass ein Tippfehler alle Ergebnisse statt eines Fehlers zurückgibt.
Statistiken akzeptieren days (Standard 30, maximal 365).
Statuscodes
| Code | Bedeutung |
|---|---|
| 200 | Erfolg |
| 201 | Erstellt |
| 400 | Fehlerhafte Anfrage oder fehlgeschlagene Validierung |
| 401 | Fehlender, fehlerhafter oder widerrufener API-Schlüssel |
| 403 | Schlüssel ist gültig, aber sein Level ist für diesen Endpunkt zu niedrig |
| 404 | Nicht gefunden oder gehört zu einem anderen Shop |
| 409 | Abgelehnt, da der Datensatz noch verwendet wird (Dateilöschung) |
| 429 | Rate-Limit erreicht - siehe unten |
| 502 | Die Anfrage wurde ausgeführt, aber das Drittanbieterziel ist fehlgeschlagen |
Ein Datensatz, der zu einem anderen Shop gehört, liefert 404 statt 403, sodass die API niemals bestätigt, dass eine ID anderswo existiert.
Rate-Limits
Zwei unabhängige Budgets, jeweils pro Schlüssel:
- 300 Anfragen pro 60 Sekunden über alle Endpunkte hinweg.
- 60 execute-Aufrufe pro Stunde zusätzlich dazu, für
POST /api/v1/http-requests/:id/test.
Wird eines der beiden überschritten, wird 429 mit einer erläuternden error-Meldung zurückgegeben. Das execute-Budget ist bewusst knapp bemessen: Eine außer Kontrolle geratene Schleife, die Live-Anfragen an einen Zahlungsanbieter abschießt, ist ein deutlich schlimmerer Fehler als ein langsames Skript.
Die Budgets gelten pro Schlüssel, nicht pro Shop, sodass eine Integration das Kontingent einer anderen nicht aufbrauchen kann.