API-Endpunkt-Referenz

Assets

Kategorien, Zuordnungen, Pakete, Links und Tags

POST /mappings und PUT /mappings/{id} akzeptieren ein optionales Objekt notify_customers ({} oder { "message": "…", "variant_ids": [ … ] }). Nach dem Commit des Schreibvorgangs reiht Alva eine Produkt-Update-Benachrichtigung für die Käufer der geschriebenen Zuordnung ein — dieselbe Kampagne wie POST /products/{shopify_product_id}/notifications unten, mit denselben Notiz-Regeln und demselben 7-Tage-Limit pro Produkt. Vor dem Schreibvorgang laufen nur die Prüfungen am eigenen Text der Notiz: Eine Notiz, die leer oder zu lang ist, eine unbekannte oder fehlerhafte Variable verwendet, mehr als fünf Metafelder nennt oder in ihrem Text einen Link enthält, ist 422 invalid_message, und es wird nichts geschrieben. Jede andere Ablehnung wird innerhalb der Antwort als data.notification mit created: false und einem error-Code gemeldet — niemals als 4xx, der Schreibvorgang der Zuordnung selbst gelingt also weiterhin. Dazu gehören ein Metafeld-Problem (invalid_message mit errors[]: ein Metafeld, das fehlt, einen nicht unterstützten Typ hat, zu lang ist oder einen Link enthält, oder eine Notiz, die zu lang ist, sobald ihre Variablen ausgefüllt sind), notification_cooldown mit next_available_at, too_many_active_notifications mit limit und active_notification_ids, no_eligible_recipients, email_disabled und archive_not_queued, wenn die Datei-Neuerstellung nicht eingereiht werden konnte. Eine brandneue Zuordnung hat noch keine Käufer und meldet no_eligible_recipients. data.notification ist nur vorhanden, wenn Sie das Flag gesendet haben. Das Flag verursacht keine zusätzlichen Rate-Limit-Kosten: Der Schreibvorgang für die Zuordnung kostet wie üblich 2 Token. Das Wiederholen desselben Idempotency-Key gibt die gespeicherte Antwort ohne zweite Kampagne zurück; um nur die Benachrichtigung zu wiederholen, rufen Sie POST /products/{shopify_product_id}/notifications mit einem neuen Schlüssel auf und nennen Sie in variant_ids die Varianten der geschriebenen Zuordnung, oder übergeben Sie dieselben variant_ids, die das Flag enthielt. Ohne variant_ids benachrichtigt dieser Endpunkt die Käufer aller Zuordnungen des Produkts, nicht nur die der von Ihnen geschriebenen.

Ein Flag pro Produkt, nicht eines pro Variante. Das Flag benachrichtigt per E-Mail nur die Käufer der geschriebenen Zuordnung, verbraucht aber das 7-Tage-Limit des ganzen Produkts. Schreiben Sie die Variantenzuordnungen eines Produkts einzeln und jeweils mit dem Flag, belegt die erste Kampagne die 7 Tage des Produkts, und die anderen melden notification_cooldown. Setzen Sie das Flag stattdessen bei einem einzigen Schreibvorgang, dem letzten, damit die Kampagne auch auf die Neuerstellungen wartet, die die früheren Schreibvorgänge eingereiht haben. Nennen Sie in variant_ids jede Variante, deren Käufer davon erfahren sollen, einschließlich der Varianten der geschriebenen Zuordnung selbst: variant_ids ersetzt den Standardumfang, statt ihn zu ergänzen.

Bestellungen und Zugriff

Der Download-URLs-Endpunkt gibt 422 withdrawal_consent_required zurück, wenn der Shop die EU-Widerrufseinwilligung aktiviert hat und für die Bestellung noch keine Einwilligung erfasst ist; Download-URLs werden ausgestellt, sobald der Kunde einwilligt.

Die Endpunkte download-urls und resend geben 409 delivery_not_yet_released zurück, wenn für das Produkt eine Verzögerung der Download-Zustellung konfiguriert ist und die Dateien des Käufers noch nicht freigeschaltet sind. Der Wert error.details.release_at ist der ISO-8601-Zeitpunkt der Freischaltung; der Endpunkt grant-downloads gibt die Bestellung vorzeitig frei.

Benachrichtigungen über Produkt-Updates

Benachrichtigen Sie die Käufer eines Produkts per E-Mail, dass es aktualisiert wurde — dieselbe Kampagne, die ein Händler mit Kunden benachrichtigen auf einer Produktseite in der App startet — aus Ihrem eigenen System. In jedem kostenpflichtigen Plan verfügbar; 403 forbidden bedeutet, dass die API für die App abgeschaltet ist (der globale Notschalter) oder dass Alva die Funktion abgeschaltet hat — kontaktieren Sie uns, wenn Sie diese Antwort erhalten. Im Pfad ist {shopify_product_id} die reine numerische Produkt-ID (empfohlen) oder eine GID, die als ein einziges Pfadsegment prozentkodiert ist (gid%3A%2F%2Fshopify%2FProduct%2F123); eine wörtliche gid://shopify/Product/123 ergibt mehrere Pfadsegmente und erreicht die Route nicht.

Request-Body (jedes Feld optional; {} benachrichtigt das ganze Produkt ohne Notiz). message: eine reine Textnotiz von bis zu 2.000 Zeichen, die als „Eine Nachricht von {Ihr Shop}:“ über der Download-Schaltfläche erscheint. Die Notiz dient dazu, zu beschreiben, was sich am Produkt geändert hat — Korrekturen, neue Dateien, was erneut heruntergeladen werden sollte —, und darf nicht für Werbeaktionen oder Rabatte verwendet werden. Sie darf {customer.first_name}, {shop.name}, {product.title} und {product.metafields.<namespace>.<key>} verwenden (bis zu fünf Metafelder vom Typ Text, Zahl, Datum oder Textliste; andere Typen werden abgewiesen). Links sind nirgends in der Notiz erlaubt — Webadressen, www., bloße Domains und E-Mail-Adressen werden abgewiesen, auch innerhalb eines Metafeldwerts —, und eine unbekannte Variable wird abgewiesen statt als Text stehen gelassen. Eine vorhandene, aber leere message wird abgewiesen; lassen Sie das Feld weg, wenn Sie keine Notiz wollen. variant_ids: beschränkt die Kampagne auf die Zuordnungen, die diese Varianten bedienen (bloße IDs oder GIDs, höchstens 100); lassen Sie es weg für das ganze Produkt. Ein leeres Array ist 400 invalid_request, niemals „alles“. dry_run: siehe Tabelle.

Wer eine E-Mail erhält. Standardmäßig jede Zuordnung des Produkts, die Dateien, Pakete oder Links hat; reine Lizenzschlüssel-Zuordnungen und personalisierte Zuordnungen werden übersprungen. Ein Käufer zählt einmal, egal wie viele anvisierte Varianten er gekauft hat, und die Schaltfläche öffnet seinen jüngsten Kauf. Käufer, die sich von Produkt-Update-E-Mails abgemeldet haben, werden übersprungen und in opted_out_count gezählt.

Eine Kampagne pro Produkt pro 7 Tage, über alle seine Varianten und jede Quelle — diesen Endpunkt, das Flag notify_customers beim Schreiben einer Zuordnung und die Schaltfläche des Händlers. Innerhalb dieser Woche, und solange eine Kampagne für das Produkt noch wartet oder sendet, lautet die Antwort 429 notification_cooldown mit Retry-After (Sekunden, bis zu sieben Tage) und error.details.next_available_at. Dies ist nicht der Token-Bucket pro Schlüssel: nicht automatisch wiederholen — eine Retry-Schleife, die auf 429 reagiert, dreht sich eine Woche lang. Planen Sie den nächsten Aufruf für next_available_at. Eine Kampagne abzubrechen gibt dem Produkt seine 7 Tage nicht zurück; prüfen Sie eine Notiz mit dry_run, bevor Sie senden. Eine Kampagne, die mit null Sendungen scheitert, gibt das Limit frei und kann einfach wiederholt werden.

Höchstens 5 Kampagnen pro Shop gleichzeitig. Ein Shop kann höchstens 5 Kampagnen gleichzeitig haben, die warten oder senden, über alle seine Produkte und jede Quelle hinweg. Eine sechste ist 429 too_many_active_notifications: error.details.limit ist die Obergrenze, und error.details.active_notification_ids listet die wartenden oder sendenden Kampagnen dieses Shops auf, die älteste zuerst. Es gibt kein Retry-After; fragen Sie GET /notifications/{id} für eine davon regelmäßig ab und versuchen Sie es erneut, sobald sie abgeschlossen ist. Ein Probelauf wird auf dieselbe Weise abgewiesen. Beim Schreiben einer Zuordnung wird dies in data.notification gemeldet, niemals als 4xx.

Eine Produkt-Update-E-Mail pro Käufer pro Tag. Ein Käufer erhält von einem Shop innerhalb von 24 Stunden höchstens eine Produkt-Update-E-Mail, gezählt pro E-Mail-Adresse, über alle Kampagnen, Produkte und Quellen hinweg. Das wird beim Senden der Kampagne angewendet: Ein Käufer, der bereits eine erhalten hat, wird übersprungen, und ein Überspringen ist kein Fehlschlag. Übersprungene Käufer werden weder in sent_count noch in failed_count oder suppressed_count gezählt, daher kann recipient_count höher sein als deren Summe. Eine Kampagne, in der jeder Käufer übersprungen wurde, endet als failed mit error: recipients_recently_notified und verbraucht die 7 Tage des Produkts nicht. Eine, in der nur einige übersprungen wurden, wird wie gewohnt abgeschlossen und verbraucht sie.

Das Warten auf das Archiv. Wird das ZIP-Archiv einer anvisierten Zuordnung gerade neu erstellt — Sie haben soeben ihre Dateien ersetzt —, wartet die Kampagne, bis die Neuerstellung abgeschlossen ist, damit kein Käufer das alte Archiv herunterlädt: waiting_for_archive: true in der 202-Antwort und bei GET. Nur eine Zuordnung, die ein ZIP-Archiv liefert, lässt eine Kampagne warten. Eine Neuerstellung, die fehlschlägt oder 60 Minuten lang keinen Fortschritt macht, während sie läuft (6 Stunden, solange sie noch auf den Start oder einen erneuten Versuch wartet), gezählt ab der letzten Statusänderung der Neuerstellung, nicht ab dem Anlegen der Kampagne, lässt die Kampagne mit null Sendungen scheitern (error ist archive_build_failed oder archive_not_ready) und gibt das Limit frei; korrigieren Sie die Dateien und versuchen Sie es erneut.

Idempotenz. Eine 202-Antwort wird unter demselben Schlüssel 24 Stunden lang wiederholt (gleiche id, keine zweite Kampagne). Ablehnungen werden nie gespeichert, ein Wiederholungsversuch mit demselben Schlüssel nach next_available_at wird also neu bewertet. Verwenden Sie pro Probelauf einen neuen Idempotency-Key: Ein wiederholter Schlüssel gibt die gespeicherte Vorschau zurück, und derselbe Schlüssel mit und ohne dry_run ist 409 idempotency_conflict.

Status bei GET. queued → processing → completed, failed oder cancelled. completed mit partial: true bedeutet, dass einige Sendungen fehlgeschlagen sind oder unterdrückt wurden (siehe sent_count, failed_count, suppressed_count) oder dass der Versand mittendrin gestoppt wurde (siehe unten). Bei failed ist error eines von interrupted, worker_crashed, send_aborted, archive_build_failed, archive_not_ready, email_disabled, invalid_message, plan_required, notifications_suspended, notifications_switched_off, nothing_sent, recipients_recently_notified, no_eligible_recipients, failed. source ist admin, api oder api_mapping.

Prüfungen während des Versands. Vor jedem Block von bis zu 500 E-Mails prüft die Kampagne den Shop erneut. Sie stoppt, wenn das Abonnement inaktiv wurde oder der Shop in den Free-Plan gewechselt ist (plan_required), Kunden-E-Mails deaktiviert wurden (email_disabled), der Versand nach Beschwerden ausgesetzt wurde (notifications_suspended) oder Alva die Benachrichtigungen abgeschaltet hat (notifications_switched_off). Stoppt sie, bevor jemand eine E-Mail erhalten hat, ist die Kampagne failed mit diesem error, und die 7 Tage des Produkts werden freigegeben. Stoppt sie, nachdem einige Käufer eine E-Mail erhalten haben, ist sie completed mit partial: true. nothing_sent bedeutet, dass jede Sendung fehlgeschlagen ist und niemand eine E-Mail erhalten hat; auch das gibt die 7 Tage frei. no_eligible_recipients bedeutet, dass zum Zeitpunkt des Versands der Kampagne niemand mehr übrig war, dem eine E-Mail gesendet werden konnte (jeder Käufer hatte sich abgemeldet oder seinen Download-Zugriff verloren); es wurde also nichts gesendet, und die 7 Tage werden freigegeben.

Ablehnungen. 402 plan_required (der Shop nutzt den Free-Plan oder sein Abonnement ist nicht aktiv), 403 forbidden (die API ist für die App abgeschaltet oder Alva hat die Funktion abgeschaltet — kontaktieren Sie uns), 403 notifications_suspended (der Versand ist nach Beschwerden ausgesetzt — kontaktieren Sie den Support), 404 mapping_not_found (keine Zuordnung für das Produkt oder eine Variante, die keine Zuordnung bedient oder die Shopify nicht als eine der Varianten des Produkts aufführt — error.details.unresolved_variant_ids), 409 multiple_mappings_match (error.details.ambiguous_variant_ids), 409 personalized_product, 422 invalid_message (error.details.errors[] nennt jede verletzte Regel, error.details.max_length ist die Obergrenze), 422 email_disabled (Kunden-E-Mails sind in der App deaktiviert), 422 no_downloadable_content, 422 no_eligible_recipients (error.details.opted_out_count), 429 notification_cooldown, 429 too_many_active_notifications (error.details.limit, error.details.active_notification_ids), 409 app_not_installed (die Notiz nennt ein Metafeld oder Sie haben variant_ids gesendet, und Alva hat keine aktive Shopify-Sitzung für den Shop, meist weil die App deinstalliert wurde), 500 internal_error (zum Beispiel konnte Shopify die Metafelder des Produkts für die Notiz nicht liefern oder die angeforderten Varianten nicht bestätigen, oder das Anlegen hat mehr als 8 Sekunden hinter den anderen Anlegevorgängen des Shops gewartet: Jeder 500er dieses Endpunkts gibt den Idempotency-Key frei, wiederholen Sie also dieselbe Anfrage mit demselben Schlüssel; hat der fehlgeschlagene Versuch die Kampagne doch eingereiht, wird die Wiederholung mit 429 notification_cooldown abgelehnt, statt eine zweite zu starten). GET und cancel antworten mit 404 notification_not_found bei einer fehlenden oder fremden ID, und cancel antwortet mit 409 notification_not_cancellable samt error.details.status, sobald eine Kampagne die Warteschlange verlassen hat. Was bei jedem Fehler zu tun ist, steht auf der Fehlerseite.

Health und Status