Hoe moet een integratie tussen RetailVista en Magento2 ingericht worden?

Dit document beschrijft de eenmalige opstart van een integratie tussen RetailVista en Magento2 websites. Met deze integratie stuurt RetailVista artikel gegevens naar Magento en haalt het orders op.

Licenties

Om gebruik te kunnen maken van de Magento2 integratie vanuit RetailVista moet er een licentie aanwezig zijn voor 'Verkooporders Plus' en een licentie 'Integratie Magento2 webshop', samen met een webshop CAL.

Webshop

In onderhoud webshops moet een nieuwe webshop worden aangemaakt. Het type moet ingesteld worden op 'Magento 2' en als API url moet het adres van de webshop opgegeven worden. De Magento2 integratie gaat er vanuit dat de API REST services in de subfolder /rest te vinden zijn achter een webshop.

Magento2 kan vanuit RetailVista op 2 manieren benaderd worden qua authenticatie. De eerste authenticatie methode is op basis van basic authentication waarbij een gebruikersnaam en een wachtwoord nodig is. Deze manier van authenticatie is alleen bruikbaar als er geen gebruik wordt gemaakt van 2FA (Two Factor Authentication). Als dat wel het geval is, dan moet er gebruik worden gemaakt van token based authenticatie. In dat geval is een API key (access token) nodig van Magento2 waarmee RetailVista de communicatie kan uitvoeren. Dit token mag niet verlopen qua lifecycle. Deze API key moet bij geavanceerde instelingen worden toegevoegd via de syntax ApiKey=<Token value> waarbij <Token Value> moet worden vervangen door het access token uit Magento. Als een ApiKey instelling gevonden wordt, dan wordt een eventueel opgegeven gebruikersnaam en wachtwoord genegeerd.

Orders

De RetailVista Magento2 integratie haalt telkens orders op die aangemaakt zijn sinds de vorige synchronisatie. Bij de eerste keer starten van deze integratie worden alle orders opgehaald die zich bevinden in Magento. Als dat niet gewenst is, dan kan via de geavanceerde instelling 'SkipCreatedBeforeDateTime' een datum en tijd opgegeven worden vanaf het moment dat orders worden geaccepteerd. De notatie is yyyy-MM-dd HH:mm waarbij de notatie wel nauwkeurig moet worden toegepast, dus 2 cijfers voor maand, 2 cijfers voro dag en toevoegen van een tijd component.

Een voorbeeld van deze instelling om alleen orders te accepteren die aangemaakt zijn na 24 januari 2022 om 15:12 uur: SkipCreatedBeforeDateTime=2022-01-24 15:12

Betalingen

Er zijn configuratie van Magento2 waar er geen betaal type code mee komt bij een betaling. Met de geavanceerde instelling 'PaymentTypeCode' kan voor situaties waar die betaal type code ontbreekt alsnog een te gebruiken code worden opgegeven.

Voorbeeld:

PaymentTypeCode=Ideal

Verder zijn er configuratie van Magento waar er een soort 'prefix' code toegevoegd wordt aan een type betaling code. Hierdoor wordt de code soms te lang (RetailVista ondersteund tot max 20 karakters) én is soms ook fictief. Met de instelling 'PaymentTypeCodeRemoveLeader=<Code>' kan een waarde opgegeven worden die automatisch wordt verwijderd als een type betaling code hiermee begint.

Voorbeeld:

PaymentTypeCodeRemoveLeader=buckaroo_magento2_

Als er nu een betaling type 'buckaroo_magento2_ideal' wordt ontvangen, dan wordt de uiteindelijke betaling type code door deze instelling 'ideal'. Die code zal uiteindelijk worden weggeschreven in het RetailVista orderbericht en bij de verwerking zal daarna gezocht woren of er een type aanbetaling met de code 'Ideal' bestaat. Het is dus wel belangrijk om deze instelling vóór de ontvangst van een orderbericht te activeren, omdat het de inhoud van het bericht bepaalt! Wijzig eventueel handmatig de inhoud van het bericht als deze instelling pas achteraf toegevoegd wordt.

Aanbetalingen

Het is mogelijk op webshops om te kiezen voor betaling van een bestelling per bankoverschrijving. Magento maakt van een dergelijke betaalwijze ook een betaling, met overigens als groot risico dat dit door RetailVista als normale (aan)betaling wordt gezien. Met behulp van de instelling 'PaymentCodeToPrepaymentRequest=<Code>' kan deze type betaling bij de verwerking van een order automatisch worden omgezet in een aanbetalingsverzoek.

Voorbeeld:

PaymentCodeToPrepaymentRequest=banktransfer

Dit zorgt er voor dat als er een betaling van het type 'banktransfer' wordt aangetroffen, dan wordt het bedrag daarvan omgezet in een aanbetalingsverzoek. De financiele administratie zal de uiteindelijk ontvangen betalingen moeten gebruiken om tegen te boeken op het openstaande aanbetalingsverzoek.

Transport

Magento vermeld in de order niet een gekozen bezorg/verzendwijze. Door de geavanceerde instelling 'TransportTypeCode=<code>' kan een vaste transport type worden opgegeven. Alle orders die binnenkomen krijgen het opgegeven transport type toegekend.

Voorbeeld:

TransportTypeCode=Pakketpost

Artikelen

De Magnento2 integratie zorgt ook voor synchronisatie van artikel informatie. De synchronisatie werkt de voorraad en prijs bij van artikelen die in Magento2 bestaan. Hiervoor wordt gebruik gemaakt van de in RetailVIsta als webshop gemarkeerde artikelen. Van die artikelen wordt bij een mutatie de vrije voorraad en de verkoopprijs overgenomen. Als een artikel verwijderd wordt uit de webshop in RetailVIsta, dan wordt door de synchronisatie de zichtbaarheid (visibility) aangepast zodat het artikel niet langer zichtbaar is in Magento. De artikel synchronisatie met Magento2 is op basis van de standaard barcode van het artikel. Als het artikel in Magento2 niet gevonden kan worden met die barcode, dan wordt het product genegeerd.

Het is mogelijk om een eerste synchronisatie met een bestaande Magento2 webshop voorzichtig op te starten. Dit is mogelijk door de geavanceerde instelling 'SyncProductNumber=<value>' te gebruiken. Als die instelling actief is, dan wordt alleen dat artikel gesynchroniseerd. Als blijkt dat van dat artikel de voorraad en prijs correct overgenomen wordt, dan is het moment aangebroken om die instelling te verwijderen en alle artikel mutaties sinds een op te geven datum en tijd opnieuw te laten versturen.