Magento-integratie — producten, bestellingen en klantgroepen

Koppel je Magento-winkel (Magento Open Source of Adobe Commerce 2.4) aan Personyze en houd Personyze er gelijk mee: je producten in de catalogus waaruit aanbevelingen putten, je bestellingen als aankoopgeschiedenis op het profiel van elke koper, en de Magento-gegevens van je klanten op hun bezoekersprofielen.

Wat het doet

Drie synchronisaties, die je elk apart aanzet:

• Producten naar uw catalogus. Elk ingeschakeld product dat zichtbaar is in je catalogus of zoekfunctie, elke 6 uur: naam, beschrijving, hoofdafbeelding, prijs en speciale prijs, merk, categorieën, en voorraad met het aantal stuks. Aanbevelingen, productwidgets en targeting op basis van de catalogus gebruiken ze meteen. Een product dat uit je winkel verdwijnt, raakt in de catalogus uitverkocht.
• Bestellingen naar aankoopgeschiedenis. De producten van elke bestelling worden aankopen op het bezoekersprofiel van de koper, gematcht op e-mailadres — voor een koper die Personyze nog niet kent, wordt een profiel aangemaakt, ook bij bestellingen als gast — met de eigen datum en het eigen bedrag van de bestelling. De eerste ronde leest een jaar aan bestellingen; daarna komen nieuwe bestellingen elke 15 minuten binnen.
• Klanten naar bezoekersprofielen. De naam, de klantgroep en de registratiedatum van elke klant, op zijn profiel, gematcht op e-mailadres, elk uur. Ze verschijnen als bezoekersattributen waarop je kunt targeten: Magento customer group, Magento customer since en Magento customer ID. Bijvoorbeeld: toon groothandelsprijzen aan bezoekers bij wie Magento customer group Wholesale is.

Wat je nodig hebt

• Magento Open Source of Adobe Commerce 2.4 (of Mage-OS).
• Een Magento-admingebruiker die integraties mag aanmaken (System → Extensions → Integrations).
• Je winkel op een openbaar https-adres. Personyze verbindt via internet met de API van je winkel.

Stap 1: Maak de integratie aan in Magento

1. Ga in je Magento-admin naar System → Extensions → Integrations → Add New Integration.
2. Geef de integratie een naam (bijvoorbeeld “Personyze”) en vul ter bevestiging je adminwachtwoord in.
3. Open het tabblad API, zet Resource Access op Custom en vink aan:
   • Catalog → Inventory — producten, categorieën en voorraad. Vink Inventory zelf aan, niet alleen Products eronder: de voorraad wordt daarlangs gelezen.
   • Sales → Operations → Orders → Actions → View — bestellingen.
   • Customers — klanten en klantgroepen.
   • Stores → Settings → All Stores — de adressen en de valuta van je winkel.
   • Stores → Attributes → Product — merknamen.

   Personyze leest alleen; het wijzigt nooit iets in je winkel.

4. Klik op Save. Klik in de lijst Integrations op Activate naast de integratie en daarna op Allow.
5. Magento toont vier waarden: Consumer Key, Consumer Secret, Access Token en Access Token Secret. Je vult ze alle vier in stap 2 in Personyze in — houd dit venster tot dan open en bewaar de waarden veilig.

Stap 2: Verbind de integratie in Personyze

1. Ga in Personyze naar Instellingen → Integraties en open Magento (onder Platform en ontwikkelaars).
2. Vul in:
   • Winkeladres — het adres dat shoppers bezoeken, bijvoorbeeld https://shop.example.com/. Een winkel in een submap, zoals https://www.example.com/shop/, werkt ook. Niet het adres van de admin.
   • De vier waarden uit stap 1: Consumer Key, Consumer Secret, Access Token en Access Token Secret.
3. Klik op Verbinden.

Personyze controleert de vier waarden bij je winkel voordat ze worden opgeslagen — waarden die niet werken, worden nooit bewaard — en zoekt uit welke van de drie synchronisaties de integratie mag lezen. De drie geheime waarden worden versleuteld bewaard en nooit meer getoond: vanaf dan staat in hun velden “(ongewijzigd)”. Daarna staat in de lade Verbonden met je winkel.

Wil je later iets wijzigen, pas dan de velden aan en klik op Controleren en opslaan. Bij dezelfde winkel en dezelfde Consumer Key kun je de geheime velden leeg laten om de opgeslagen waarden te houden.

Personyze ondertekent elk verzoek met de vier waarden van de integratie (OAuth 1.0a), zoals Magento dat van een integratie verwacht. Je hoeft “Allow OAuth Access Tokens to be used as standalone Bearer tokens” in de OAuth-instellingen van Magento niet aan te zetten.

Stap 3: Zet aan wat je wilt synchroniseren

Zet onder Wat er wordt gesynchroniseerd elke synchronisatie aan die je wilt: Producten naar uw catalogus, Bestellingen naar aankoopgeschiedenis en Klanten naar bezoekersprofielen. Elke rij toont wat ze van de integratie nodig heeft — Producten, Bestellingen of Klanten — in het groen als de integratie het mag lezen, en in het rood, met “Niet toegestaan voor de Integration”, als dat niet mag (zie Problemen oplossen).

Een synchronisatie die je aanzet, toont “Start binnen 5 minuten”. Na een ronde zegt elke rij wat ze heeft gedaan, bijvoorbeeld “7 producten · 1 okt.”, “8 aankopen sinds 1 okt.” of “3 profielen · 1 okt.”. Nu synchroniseren voert een synchronisatie uit bij de volgende ronde, binnen 5 minuten, zonder op het schema te wachten.

Hoe de gegevens worden gebruikt

Producten

Elk product is één catalogusitem, herkend aan zijn Magento-product-ID. De link bestaat uit het adres van je winkel, de URL-sleutel van het product en het URL-achtervoegsel voor producten (.html tenzij je dat hebt gewijzigd).

• Prijzen: een speciale prijs telt zolang vandaag binnen de van/tot-datums valt, en alleen als hij lager is dan de prijs — dan is de prijs de gewone prijs en de speciale prijs de actieprijs. Catalogusprijsregels worden niet toegepast op de gesynchroniseerde prijzen.
• Configureerbare producten (bijvoorbeeld een T-shirt in maten) zijn één catalogusitem, met de laagste prijs van hun ingeschakelde varianten en de voorraad van hun varianten bij elkaar opgeteld. De varianten zelf (“Not Visible Individually”) worden niet als aparte producten gesynchroniseerd.
• Voorraad: een product is op voorraad zoals Magento aangeeft; het aantal stuks wordt alleen bijgehouden waar Magento de voorraad van het product beheert.
• Merk: het attribuut brand of manufacturer van je winkel.
• Categorieën: de namen van de categorieën van het product.
• Uitgeschakelde producten, producten die niet afzonderlijk zichtbaar zijn en producten zonder URL-sleutel worden niet gesynchroniseerd.
• Er worden tot 50.000 producten gesynchroniseerd. Van een grotere winkel worden de eerste 50.000 gesynchroniseerd, en de rij Producten meldt dat.

Aankopen

De aankopen van een bestelling zijn de producten ervan (een configureerbaar product telt als het product, niet als zijn variant). Geannuleerde of terugbetaalde hoeveelheden worden weggelaten, en de korting van elke regel wordt van het bedrag ervan afgetrokken. Geannuleerde bestellingen, volledig terugbetaalde (gesloten) bestellingen en bestellingen zonder e-mailadres leveren geen aankopen op.

Productfeeds

Importeert je account ook een productfeed, dan kan een product dat in beide staat twee keer in de catalogus verschijnen. Houd per product één bron aan — de rij Producten waarschuwt je als het account een feed heeft.

Loskoppelen

Klik in de lade op het prullenbakpictogram naast “Verbonden met …”. Het synchroniseren stopt; de producten, aankopen en profielen die al zijn gesynchroniseerd, blijven staan. De integratie blijft in je Magento-admin — verwijder haar daar als je haar niet meer nodig hebt.

Problemen oplossen

“There is no Magento API at …”

Het adres is niet dat van de winkel zelf. Vul het adres in dat shoppers bezoeken, zoals https://shop.example.com/ — niet het adres van de admin.

“Magento did not accept these keys.”

Controleer of de integratie in Magento Active is, en vul alle vier de waarden opnieuw in vanuit de details van de integratie. Heb je in Magento op Reauthorize geklikt, dan heeft Magento een nieuw Access Token en Access Token Secret uitgegeven — vul die in.

“The integration may read nothing Personyze syncs.”

De integratie heeft geen van de resources uit stap 1. Bewerk haar in Magento → API, vink ze aan, klik op Save, daarna op Reauthorize en Allow, en vul de nieuwe waarden in Personyze in.

Een synchronisatierij is rood en zegt “Niet toegestaan voor de Integration”

Bewerk in Magento de integratie → API, vink de resource aan die de rij noemt (zie stap 1), klik op Save, daarna op Reauthorize en Allow. Vul het nieuwe Access Token en Access Token Secret in Personyze in en klik op Controleren en opslaan.

“Personyze cannot connect to …”

Personyze bereikt je winkel via internet, en alleen via https. Een winkel op een privénetwerk of op gewoon http kan niet worden verbonden.

“The signature is invalid”, terwijl de vier waarden kloppen

Magento controleert de handtekening van elk verzoek tegen het adres waarop het denkt te zijn aangeroepen. Staat je winkel achter een proxy, load balancer of CDN die https afhandelt en gewoon http doorgeeft aan Magento, dan moet Magento te horen krijgen dat het verzoek via https kwam — via zijn offloader-header, meestal X-Forwarded-Proto: https, ingesteld door de proxy. Een winkel waarvan de beveiligde pagina’s normaal werken, heeft dit al. Bij het verbinden verschijnt dit als “Magento did not accept these keys.”; tijdens een synchronisatie staan de eigen woorden van Magento — “The signature is invalid” — in de reden die de lade toont.

“The store redirected to …”

Het adres dat je hebt ingevuld, stuurt bezoekers door naar een ander adres (bijvoorbeeld van example.com naar www.example.com). Vul het adres in waarnaar wordt doorgestuurd.

De lade toont de weigering van Magento in plaats van “Verbonden met”

Magento weigerde de sleutels tijdens een synchronisatie — de integratie is gedeactiveerd, verwijderd of opnieuw geautoriseerd. Personyze stopt meteen met het gebruik van de koppeling in plaats van het opnieuw te proberen, en de lade toont de reden van Magento op de plek waar “Verbonden met” stond. Vul de huidige vier waarden van de integratie in en klik op Verbinden. Een opnieuw verbonden winkel houdt zijn synchronisaties zoals ze waren.

Elk product staat als op voorraad, zonder aantallen

De integratie mag de voorraad niet lezen: vink Catalog → Inventory zelf aan (stap 1), autoriseer opnieuw en vul de nieuwe waarden in Personyze in.

Prijzen wijken af van de webwinkel

Catalogusprijsregels worden niet toegepast op gesynchroniseerde prijzen; speciale prijzen wel.

De firewall van de winkel blokkeert de verbinding

Staat je winkel achter een firewall die geautomatiseerde verzoeken blokkeert, sta dan verzoeken toe met de user agent Personyze/1.0 (+https://www.personyze.com).

Gerelateerd

• Integraties — alle andere koppelingen.
• Shopify-integratie (koppelen via API) — dezelfde drie synchronisaties voor een Shopify-winkel.
• Personyze installeren — de trackingcode die je webwinkel nodig heeft.
• Aanbevelingen — begin hier — widgets gebouwd op de gesynchroniseerde catalogus en aankopen.
• De product-/contentfeed instellen — de andere manier om de catalogus te vullen.
• Targetingregels — targeten op Magento customer group.
• Problemen oplossen: een integratie synchroniseert niet meer