Ontwikkelaarstools¶
De pagina For developers biedt API-toegang, webhookconfiguratie, headless modus en geavanceerde integratieopties. Open haar via For developers in het linkermenu.
Wijzigingen aan selectievakjes en webhook-URL's op deze pagina worden toegepast wanneer je op Save klikt in de opslagbalk. De tokenknoppen en Generate Secret werken meteen. Enable headless mode heeft ook Save nodig.
Storefront API¶
De Storefront API is een JavaScript-interface (window.GiftHeroAPI) waarmee je je eigen cadeaubonselectie- en aankoopinterface op je webshop bouwt.
- Enable storefront API: schakel dit in om de JavaScript-API op je cadeaubon-productpagina te laden. De cadeaubon-interface die de app genereert, wordt op die pagina uitgeschakeld, zodat je ontwikkelaar de interface bouwt.
- Disable gift card page animation: verschijnt zodra de storefront API aan staat. Verwijdert de geanimeerde cadeaubonpagina van de app, zodat je een eigen cadeaubonpagina kunt bouwen.
De API leest geen saldi. Ze verzamelt de cadeaubonkeuzes (bedrag, ontwerp, bericht, ontvanger) en voegt de cadeaubon aan de winkelwagen toe.
Volledige API-referentie: Storefront API
REST API¶
De REST API laat je Gift Card Hero koppelen aan externe systemen, zoals CRM's, analysedashboards, loyaliteitsplatforms en meer.
Inschakelen¶
Vink Enable REST API aan en sla op. Klik daarna op Send me access token. Gift Card Hero stuurt het toegangstoken naar het e-mailadres van de winkelcontact dat op de pagina staat.
Je winkel heeft één API-token tegelijk, gedeeld door elke koppeling die het gebruikt:
- Send me access token geeft een nieuw token uit. Het vorige token werkt meteen niet meer, dus werk je koppelingen bij met het nieuwe token. Om het token opnieuw op te zoeken, zoek je de eerdere e-mail op.
- Revoke access token schakelt het huidige token uit zonder een nieuw uit te geven. Gebruik dit als het token mogelijk is gelekt of een partner geen toegang meer nodig heeft.
- Als je Enable REST API uitschakelt, wordt het token ook ingetrokken.
Details: Je API-token beheren
Op de pagina staat een link naar de Postman collection voor snelle verkenning van de API. Show available API endpoints toont de belangrijkste endpoints op de pagina zelf.
Beschikbare endpoints¶
| Methode | Endpoint | Beschrijving |
|---|---|---|
POST |
/api/external/gift-cards |
Maak een cadeaubon aan |
POST |
/api/external/gift-cards/{id}/disable |
Schakel een cadeaubon uit |
GET |
/api/external/gift-cards |
Toon cadeaubonnen (filterbaar op status) |
GET |
/api/external/gift-cards/{id} |
Haal één cadeaubon op |
GET |
/api/external/gift-cards/search?query=... |
Zoek cadeaubonnen (bijvoorbeeld last_characters:mnop) |
PUT |
/api/external/gift-cards/{id} |
Werk een cadeaubon bij |
PUT |
/api/external/gift-cards/{id}/balance |
Werk het saldo van een cadeaubon bij |
POST |
/api/external/gift-cards/{id}/redeem |
Wissel een cadeaubon in vanuit een POS- of kassa-app (verstuurt de inwisselmelding en registreert de vestiging) |
GET |
/api/external/gift-cards/transactions |
Cadeaubonnen met hun transacties, in pagina's |
POST |
/api/external/gift-cards/assign-to-order |
Koppel je eigen cadeauboncodes aan een bestelling |
Volledige API-referentie: REST API-referentie
Webhooks¶
Gift Card Hero kan HTTP POST-verzoeken naar je server sturen wanneer specifieke cadeaubongebeurtenissen plaatsvinden.
Webhookinstellingen verschijnen op deze pagina zodra Enable REST API aan staat.
Een webhook-secret instellen¶
Klik op Generate Secret om een ondertekeningssecret aan te maken. Kopieer het direct uit de banner, want het wordt maar één keer getoond. Gebruik het op je server om te controleren dat binnenkomende payloads van Gift Card Hero komen. De handtekening wordt verstuurd in de header X-GiftHero-Signature (HMAC-SHA256).
Klik op Regenerate Secret om het secret te vervangen, bijvoorbeeld als het is gelekt. Het oude secret werkt meteen niet meer, dus werk je server bij met het nieuwe.
Webhook-endpoints¶
Configureer je server-URL's voor deze webhooktypes:
| Veld op de pagina | Wanneer het wordt verstuurd |
|---|---|
| Order with gift card webhook URL | Cadeaubonnen van een bestelling worden door Gift Card Hero verwerkt |
| Gift card payment webhook URL | Er wordt een bestelling aangemaakt die met een cadeaubon is betaald |
| Gift card balance webhook URL | Wordt momenteel niet verstuurd (zie de integratiegids) |
Vul je endpoint-URL in elk veld in en sla op. Een nieuwe of gewijzigde URL moet beginnen met https:// en bereikbaar zijn vanaf het internet. Adressen in privénetwerken worden bij het opslaan geweigerd.
Volledige integratiegids: Webhooks-integratiegids
Aangepaste codeeditor¶
Voeg aangepaste CSS toe aan de webshopcomponenten van Gift Card Hero, zonder je Shopify-thema direct aan te passen.
Klik op Open custom code editor. Hij opent het tabblad Custom code in Settings.
Je CSS wordt toegevoegd aan de cadeaubon-productpagina's, de cadeaubonpagina en de pagina's van fysieke cadeaubonproducten en cadeaubonproducten met vrij bedrag. Hij wordt niet aan de rest van je winkel toegevoegd. Gebruik hem om de uitstraling van de cadeaubonbouwer en de cadeaubonpagina aan te passen. Klik op Save in de opslagbalk om je wijzigingen toe te passen.
Alleen CSS
De editor accepteert alleen CSS. CSS die </style bevat, wordt bij het opslaan geweigerd. Aangepaste JavaScript die vóór deze wijziging voor je winkel was ingesteld, blijft werken, maar kan hier niet meer worden bewerkt. Neem contact op met support om die te wijzigen.
Cadeaubongegevens opslaan in een metafield¶
Vink Save a gift card data to a metafield aan om de gegevens van elke cadeaubon (ontwerp, bericht, afzender) op te slaan in een Shopify-metafield van je winkel:
- Namespace:
gift_hero - Key:
cards_data
De gegevens worden gekoppeld aan de laatste vier tekens van de cadeauboncode. Zo zijn ze beschikbaar in Shopify-e-mailsjablonen tijdens het aanmaken van cadeaubonnen en in je eigen Liquid-sjablonen.
Disable gift card page animation for templates with suffix schakelt de cadeaubonpagina van de app uit voor cadeaubonnen die een sjabloonachtervoegsel hebben (zie template_suffix in de REST API), zodat jouw eigen sjabloon wordt getoond.
Headless modus¶
Schakel Headless Mode in voor aangepaste of headless Shopify-webshops die niet het standaard Shopify-themasysteem gebruiken.
Klik op Enable headless mode (de statusbadge verandert in Enabled). Er verschijnt een codefragment met tijdelijke waarden die je vervangt door de gegevens van je winkel:
| Tijdelijke waarde | Vervangen door |
|---|---|
[MONEY_FORMAT] |
De bedragnotatie van je winkel |
[PRODUCT_ID] |
De numerieke Shopify-ID van je cadeaubonproduct |
[MYSHOPIFY_DOMAIN] |
Het .myshopify.com-domein van je winkel |
[ADD_TO_CART_CALLBACK] |
Je eigen JavaScript-functie voor toevoegen aan de winkelwagen |
[LOCALE] |
De taalcode van je vertalingen (bijv. en, fr). en is de standaard |
Kopieer het fragment en integreer het in de codebase van je eigen webshop.
Volledige installatiegids: Headless-integratiegids
Aangepaste fulfillment¶
Deze sectie verschijnt alleen voor winkels die de optie zelf-fulfillment gebruiken. Daarmee is Gift Card Hero volledig verantwoordelijk voor het aanmaken en leveren van de cadeaubonnen van een bestelling, in plaats van de automatische cadeaubonfulfillment van Shopify.
Schakel eerst de automatische fulfillment in Shopify uit
Kies in je Shopify-instellingen voor afrekenen (orderverwerking) Don't fulfill any of the order's line items automatically. De pagina linkt naar Check settings en een Shopify-gids. Fulfill cadeaubonnen in een bestelling niet zelf. Ze moeten onvervuld blijven.
De badge toont de huidige status (Enabled of Disabled). Klik op Enable custom fulfilment of Disable custom fulfilment om te wisselen.