Entwicklertools¶
Die Seite For developers bietet API-Zugriff, Webhook-Konfiguration, Headless-Modus und erweiterte Integrationsoptionen. Öffnen Sie sie über For developers in der linken Navigation.
Änderungen an Kontrollkästchen und Webhook-URLs auf dieser Seite werden übernommen, sobald Sie in der Speicherleiste auf Save klicken. Die Token-Schaltflächen und Generate Secret wirken sofort. Enable headless mode braucht ebenfalls Save.
Storefront API¶
Die Storefront API ist eine JavaScript-Schnittstelle (window.GiftHeroAPI), mit der Sie Ihre eigene Auswahl- und Kaufoberfläche für Geschenkgutscheine in Ihrem Onlineshop bauen.
- Enable storefront API: Aktivieren, um die JavaScript-API auf Ihrer Produktseite für Geschenkgutscheine zu laden. Die von der App erzeugte Oberfläche für Geschenkgutscheine wird auf dieser Seite ausgeschaltet, sodass Ihr Entwickler die Oberfläche selbst baut.
- Disable gift card page animation: Erscheint, sobald die Storefront API aktiv ist. Entfernt die animierte Geschenkgutschein-Seite der App, damit Sie eine eigene Seite bauen können.
Die API liest keine Guthaben aus. Sie erfasst die Auswahl des Geschenkgutscheins (Betrag, Design, Nachricht, Empfänger) und legt den Geschenkgutschein in den Warenkorb.
Vollständige API-Referenz: Storefront API
REST API¶
Die REST API ermöglicht Ihnen, Gift Card Hero mit externen Systemen zu verbinden, etwa CRM-Systemen, Analyse-Dashboards, Loyalty-Plattformen und anderen.
Aktivieren¶
Setzen Sie den Haken bei Enable REST API und speichern Sie. Klicken Sie dann auf Send me access token. Gift Card Hero sendet den API-Zugriffstoken an die Shop-Kontakt-E-Mail-Adresse, die auf der Seite angezeigt wird.
Ihr Shop hat jeweils ein API-Token, das von allen Integrationen gemeinsam genutzt wird:
- Send me access token stellt ein neues Token aus. Das bisherige funktioniert sofort nicht mehr. Aktualisieren Sie daher Ihre Integrationen mit dem neuen Token. Um das Token erneut abzurufen, suchen Sie stattdessen die frühere E-Mail.
- Revoke access token deaktiviert das aktuelle Token, ohne ein neues auszustellen. Nutzen Sie das, wenn das Token möglicherweise abhandengekommen ist oder ein Partner keinen Zugriff mehr braucht.
- Wenn Sie Enable REST API ausschalten, wird das Token ebenfalls widerrufen.
Details: Ihr API-Token verwalten
Auf der Seite gibt es einen Link zur Postman collection für die schnelle Erkundung der API. Show available API endpoints listet die wichtigsten Endpunkte direkt auf der Seite auf.
Verfügbare Endpunkte¶
| Methode | Endpunkt | Beschreibung |
|---|---|---|
POST |
/api/external/gift-cards |
Geschenkgutschein erstellen |
POST |
/api/external/gift-cards/{id}/disable |
Geschenkgutschein deaktivieren |
GET |
/api/external/gift-cards |
Geschenkgutscheine auflisten (filterbar nach Status) |
GET |
/api/external/gift-cards/{id} |
Einen einzelnen Geschenkgutschein abrufen |
GET |
/api/external/gift-cards/search?query=... |
Geschenkgutscheine suchen (zum Beispiel last_characters:mnop) |
PUT |
/api/external/gift-cards/{id} |
Geschenkgutschein aktualisieren |
PUT |
/api/external/gift-cards/{id}/balance |
Guthaben eines Geschenkgutscheins aktualisieren |
POST |
/api/external/gift-cards/{id}/redeem |
Geschenkgutschein über eine POS- oder Kassen-App einlösen (sendet die Einlösungsbenachrichtigung, erfasst die Filiale) |
GET |
/api/external/gift-cards/transactions |
Geschenkgutscheine mit ihren Transaktionen, paginiert |
POST |
/api/external/gift-cards/assign-to-order |
Eigene Geschenkgutschein-Codes einer Bestellung zuweisen |
Vollständige API-Referenz: REST API-Referenz
Webhooks¶
Gift Card Hero kann HTTP-POST-Anfragen an Ihren Server senden, wenn bestimmte Ereignisse zu Geschenkgutscheinen eintreten.
Die Webhook-Einstellungen erscheinen auf dieser Seite, sobald Enable REST API aktiv ist.
Webhook-Geheimnis einrichten¶
Klicken Sie auf Generate Secret, um ein Signatur-Geheimnis zu erzeugen. Kopieren Sie es sofort aus dem Banner, denn es wird nur einmal angezeigt. Verwenden Sie es auf Ihrem Server, um zu prüfen, dass eingehende Daten von Gift Card Hero stammen. Die Signatur wird im Header X-GiftHero-Signature übermittelt (HMAC-SHA256).
Klicken Sie auf Regenerate Secret, um das Geheimnis zu erneuern, zum Beispiel wenn es abhandengekommen ist. Das alte Geheimnis funktioniert sofort nicht mehr. Aktualisieren Sie daher Ihren Server mit dem neuen.
Webhook-Endpunkte¶
Konfigurieren Sie die Server-URLs für diese Webhook-Typen:
| Feld auf der Seite | Wann es auslöst |
|---|---|
| Order with gift card webhook URL | Geschenkgutscheine einer Bestellung werden von Gift Card Hero verarbeitet |
| Gift card payment webhook URL | Eine Bestellung wird angelegt, die mit einem Geschenkgutschein bezahlt wurde |
| Gift card balance webhook URL | Wird derzeit nicht gesendet (siehe Integrationsanleitung) |
Tragen Sie in jedes Feld Ihre Endpunkt-URL ein und speichern Sie. Eine neue oder geänderte URL muss mit https:// beginnen und aus dem Internet erreichbar sein. Adressen aus privaten Netzwerken werden beim Speichern abgelehnt.
Vollständige Integrationsanleitung: Webhook-Integrationsanleitung
Editor für eigenen Code¶
Fügen Sie eigenes CSS zu den Storefront-Komponenten von Gift Card Hero hinzu, ohne Ihr Shopify-Theme direkt zu ändern.
Klicken Sie auf Open custom code editor. Er öffnet den Tab Custom code in Settings.
Ihr CSS wird den Produktseiten für Geschenkgutscheine, der Geschenkgutschein-Seite und den Seiten von physischen Geschenkgutschein-Produkten und Geschenkgutscheinen mit frei wählbarem Betrag hinzugefügt. Es wird nicht auf den übrigen Shop angewendet. Nutzen Sie es, um das Aussehen des Geschenkgutschein-Builders und der Geschenkgutschein-Seite anzupassen. Klicken Sie in der Speicherleiste auf Save, um Ihre Änderungen zu übernehmen.
Nur CSS
Der Editor akzeptiert nur CSS. CSS, das </style enthält, wird beim Speichern abgelehnt. Eigenes JavaScript, das vor dieser Änderung für Ihren Shop eingerichtet wurde, funktioniert weiter, lässt sich hier aber nicht mehr bearbeiten. Wenden Sie sich an den Support, um es zu ändern.
Geschenkgutschein-Daten in Metafield speichern¶
Setzen Sie den Haken bei Save a gift card data to a metafield, um die Daten jedes Geschenkgutscheins (Design, Nachricht, Absender) in einem Shopify-Metafield Ihres Shops zu speichern:
- Namespace:
gift_hero - Key:
cards_data
Die Daten werden über die letzten vier Zeichen des Geschenkgutschein-Codes zugeordnet. So sind sie in Shopify-E-Mail-Vorlagen während der Erstellung des Geschenkgutscheins und in Ihren eigenen Liquid-Vorlagen verfügbar.
Disable gift card page animation for templates with suffix schaltet die animierte Geschenkgutschein-Seite der App für Geschenkgutscheine aus, die ein Vorlagen-Suffix haben (siehe template_suffix in der REST API). Stattdessen wird Ihre eigene Vorlage angezeigt.
Headless-Modus¶
Aktivieren Sie den Headless-Modus für individuelle oder Headless-Storefronts von Shopify, die das Standard-Theme-System von Shopify nicht verwenden.
Klicken Sie auf Enable headless mode (das Statusabzeichen wechselt zu Enabled). Ein Code-Snippet erscheint mit Platzhaltern, die Sie durch die Angaben Ihres Shops ersetzen:
| Platzhalter | Ersetzen durch |
|---|---|
[MONEY_FORMAT] |
Das Geldformat Ihres Shops |
[PRODUCT_ID] |
Die numerische Shopify-ID Ihres Geschenkgutschein-Produkts |
[MYSHOPIFY_DOMAIN] |
Die .myshopify.com-Domain Ihres Shops |
[ADD_TO_CART_CALLBACK] |
Ihre eigene JavaScript-Funktion für „In den Warenkorb“ |
[LOCALE] |
Der Gebietsschema-Code Ihrer Übersetzungen (z. B. en, fr). en ist die Standardeinstellung |
Kopieren Sie das Snippet und integrieren Sie es in Ihre eigene Storefront-Codebasis.
Vollständige Einrichtungsanleitung: Headless-Integrationsanleitung
Individueller Versand¶
Dieser Abschnitt erscheint nur bei Shops, die die Option Selbstversand nutzen. Dabei ist Gift Card Hero vollständig dafür verantwortlich, die Geschenkgutscheine einer Bestellung zu erstellen und zuzustellen, statt der automatischen Geschenkgutschein-Erfüllung von Shopify.
Automatische Erfüllung in Shopify zuerst ausschalten
Wählen Sie in den Checkout-Einstellungen (Bestellverarbeitung) von Shopify die Option Don't fulfill any of the order's line items automatically. Die Seite verlinkt auf Check settings und einen Leitfaden von Shopify. Erfüllen Sie Geschenkgutscheine einer Bestellung nicht selbst. Sie müssen unerfüllt bleiben.
Das Abzeichen zeigt den aktuellen Status (Enabled oder Disabled). Klicken Sie auf Enable custom fulfilment oder Disable custom fulfilment, um umzuschalten.