Webwinkel koppelen met MailPlus ecom via de REST API

Handleiding

Webwinkel koppelen met MailPlus eCom via de REST API

Deze handleiding is in te zetten voor eCom Business en Enterprise

Inleiding MailPlus eCom is een e-mail marketing oplossing voor webwinkels. Met MailPlus eCom kan de marketeer eenvoudig professionele nieuwsbrieven opstellen en versturen met productinformatie uit de webwinkel. Het is ook mogelijk om vanuit de webwinkel automatische geavanceerde event-driven marketingcampagnes te aan te sturen naar aanleiding van een gebeurtenis in de webwinkel. Denk daarbij aan een welkomst e-mail bij een nieuwsbriefinschrijving, een automatische e-mail als iemand zijn winkelwagen achterlaat zonder afgerekend te hebben, product review-campagnes, et cetera. In de rapportage van elke verstuurde nieuwsbrief is terug te zien wat de effectiviteit is geweest en hoeveel omzet ermee is gegenereerd. MailPlus eCom is bedoeld om gekoppeld te zijn met een webwinkel. Zowel contacten als producten kunnen real-time vanuit de webwinkel worden gesynchroniseerd naar MailPlus eCom. Zo kan de marketeer binnen een handomdraai via een gebruiksvriendelijke editor een productennieuwsbrief creëren. Omdat de contacten uit de webshop door de synchronisatie al in MailPlus staan, kan de nieuwsbrief op elk gewenst moment verstuurd worden zonder extra handelingen van de marketeer. Voor een goede koppeling tussen de webwinkel en MailPlus eCom is een REST API beschikbaar. Er dient hiervoor wel aan webwinkelzijde een plug in ontwikkeld te worden die met deze REST API communiceert. Dit document beschrijft wat een ontwikkelaar moet weten om zo’n plug in te maken. Het is niet altijd nodig om zelf een plug in te ontwikkelen. Voor sommige webwinkelsystemen, zoals Magento, is een gratis connector beschikbaar.

Handleiding: Webwinkel koppelen met MailPlus eCom via de REST API

Inhoudsopgave Introductie........................................................................................ 1 1 Globale werking van de koppeling................................................. 2 1.1 Schema van de koppeling............................................................. 2 2 Opzet koppeling op basis van REST API......................................... 4 2.1 OAuth (Open Authorization)......................................................... 4 2.2 API Key en Secret............................................................................ 4 2.3 API URL............................................................................................ 5 2.4 API Methodes.................................................................................. 5 2.5 Foutafhandeling............................................................................. 6 2.6 Maak gebruik van een wachtrij..................................................... 7 3 Contacten synchroniseren.............................................................. 9 3.1 Welke contacteigenschappen worden gesynchroniseerd?....... 9 3.2 Permissies....................................................................................... 9 3.3 Contact toevoegen aan Mailplus eCom..................................... 10 3.4 Contact wijzingen in MailPlus eCom.......................................... 10 3.5 Contact verwijderen uit MailPlus eCom.................................... 10 4 Wijzigingen, afmeldingen en bounces......................................... 11 4.1 Wijzigingen ophalen uit MailPlus eCom.................................... 11 4.2 Afmeldingen ophalen uit MailPlus eCom.................................. 12 4.3 Bounces ophalen uit MailPlus eCom......................................... 12 5 Producten Synchroniseren........................................................... 14 5.1 Producteigenschappen................................................................ 15 5.2 Product toevoegen aan MailPlus eCom.................................... 16 5.3 Product wijzigen in MailPlus eCom............................................ 16 5.4 Product verwijderen uit MailPlus eCom.................................... 16 6 Orders Synchroniseren.................................................................. 17 6.1 Ordereigenschappen................................................................... 17 6.2 Order toevoegen aan MailPlus eCom........................................ 17 6.3 Order wijzigen in MailPlus eCom................................................ 17 6.4 Order verwijderen uit MailPlus eCom....................................... 17


7 Conversie doorgeven..................................................................... 18 7.1 Conversie winkelwagen aangemaakt doorgeven..................... 19 7.2 Conversie bestelling geplaatst doorgeven................................ 19 8 Automatische campagnes............................................................. 21 8.1 Welkomstcampagne bij aanmelding nieuwsbrief.................... 22 8.2 Verlaten winkelwagen campagne.............................................. 22 8.3 Product review campagne........................................................... 23 9 Referentie REST API methodes..................................................... 24 9.1 Methode: Contact toevoegen..................................................... 24 9.2 Methode: Contact wijzigen.......................................................... 25 9.3 Methode: Contact ophalen......................................................... 27 9.4 Methode: Gewijzigde contacten ophalen.................................. 29 9.5 Methode: Gebouncede contacten ophalen.............................. 31 9.6 Methode: Contacteigenschappen ophalen............................... 34 9.7 Methode: Product toevoegen..................................................... 36 9.8 Methode: Product wijzigen......................................................... 39 9.9 Methode: Product verwijderen................................................... 40 9.10 Methode: Product ophalen......................................................... 40 9.11 Methode: Order toevoegen........................................................ 42 9.12 Methode: Order wijzigen............................................................. 43 9.13 Methode: Order verwijderen...................................................... 44 9.14 Methode: Winkelwagen aangemaakt doorgeven..................... 45 9.15 Methode: Winkelwagen geconverteerd doorgeven................. 45 9.16 Methode: Alle campagnes ophalen............................................ 47 9.17 Methode: Campagne triggeren.................................................. 48 9.18 Methode: Campagne stoppen.................................................... 49 10 Aanvullende informatie................................................................ 51


Introductie MailPlus eCom kent 2 productversies:

1) MailPlus eCom Business MailPlus eCom Business is bedoeld voor de professionele webwinkelier die naast een productennieuwsbrief ook diverse automatische, eventdriven marketingcampagnes verstuurt. Binnen MailPlus eCom Business zijn diverse kant-en-klare automatische campagnes beschikbaar om extra omzet te genereren: Welkom nieuwsbrief-, Verlaten winkelwagen-, Product review-, Win back- en Verjaardagscampagne.

2) MailPlus Enterprise MailPlus eCom Enterprise is een stabiele, schaalbare e-mail marketing oplossing die volledig kan integreren. Naast diverse kant-en-klare automatische campagnes, kan de marketeer ook eigen campagnes creëren. Daarnaast biedt MailPlus eCom Enteprise geavanceerde segmentatiemogelijkheden, zoals “Nieuwsbrief-Op-Maat” waarbij (delen van de) reguliere nieuwsbrief zijn afgestemd op de individuele ontvanger op basis van zijn of haar interesses of op basis van zijn of haar gedrag in de webwinkel. In dit document beschrijft hoe een ontwikkelaar een koppeling kan ontwikkelen tussen een webwinkel en MailPlus eCom. In hoofdstuk 1 wordt eerst ingegaan op de globale werking van de koppeling. Hoofdstuk 2 beschrijft de algemene opzet van de koppeling op basis van REST API. In de hoofdstukken die daarop volgen worden de hoofdonderdelen behandelt van de koppeling, te weten: Contacten synchroniseren, Bounces en Afmeldingen ophalen, Producten synchroniseren, Conversie doorgeven en Campagnes triggeren. Hoofdstuk 9 is een Referentie van alle REST API methodes. Het document wordt beëindigd met een hoofdstuk “Aanvullende informatie”.


1

1

Globale werking van de koppeling Een koppeling tussen een webwinkel en MailPlus eCom kan uit grofweg uit 5 onderdelen bestaan: • • • •

Real-time synchronisatie van contactgegevens Real-time synchronisatie van productgegevens Real-time synchronisatie van ordergegevens Doorgeven van conversie in de webwinkel naar aanleiding van de nieuwsbrief • Triggeren van automatische event-driven marketingcampagnes

1.1

Schema van een koppeling

In bovenstaand schema is te zien dat MailPlus eCom beschikt over een REST API. Hiermee wordt de koppeling gelegd. Daarvoor is aan webwinkelzijde een stukje software nodig. We noemen dit een “connector” of een plug in. Dit document beschrijft hoe een ontwikkelaar zo’n connector kan ontwikkelen. De contacten, producten en orders in de database van de webwinkel worden door de connector real-time met MailPlus eCom synchroon gehouden. Dit wordt gesymboliseerd door de pijl naar rechts.


2

De webwinkel is daarbij het leidende systeem. Er is daarbij één uitzondering. Dat is wanneer ontvangers van een nieuwsbrief hun gegevens wijzigen op een landingspagina in MailPlus eCom. De gewijzigde contactgegevens worden automatisch weer teruggestuurd en doorgevoerd in de webwinkel. Dat is de pijl naar links in het schema. De connector geeft daarnaast direct een signaal door aan MailPlus eCom op het moment dat er conversie heeft plaatsgevonden in de webwinkel naar aanleiding van de nieuwsbrief. Dit wordt gesymboliseerd door de pijl naar rechts. Ten slotte, kan de webwinkel event-driven marketing campagnes aansturen op het moment dat er een gebeurtenis plaatsvindt in de webwinkel. Zo kan de webwinkel ervoor zorgen dat er een e-mail wordt verstuurd vanuit MailPlus eCom naar iemand die zijn winkelwagen heeft achtergelaten zonder de bestelling te hebben afgerond. Ook dit wordt gesymboliseerd door de pijl naar rechts.


3

2

Opzet koppeling op basis van REST API Het is van belang dat de service kan verifiëren of de API aanroepen wel van de juiste bron (uw webshop) komen. Daarom vindt er bij bij het gebruik van de REST API service bij iedere aanroep authenticatie plaats.

OAuth (Open Authorization) 2.1

De authenticatie is op basis van 2-leg Open Authorization (OAuth). Bij iedere API-aanroep dient er een zogenaamde Key en Secret meegegeven te worden, waarmee de API-service kan bepalen of de aanroep in orde is. De tokens kunnen nul blijven.

API Key en Secret 2.2

Keys en Secrets zijn altijd gekoppeld aan één MailPlus-account. Er dient eerst in het MailPlus-account een Key en Secret aangemaakt te worden voor de webshop waarmee MailPlus gekoppeld wordt. Ga hiervoor naar het vierde tabblad “MailPlus Instellingen” op de startpagina. Hier kunt een nieuwe autorisatie aanmaken. U dient een autorisatie een naam te geven. Het is daarbij handig om een logische naam te geven. Bijvoorbeeld de naam van de webshop. Als u de autorisatie heeft aangemaakt, toont MailPlus de Key en Secret die u nodig heeft in de webshop. De API Key is in feite uw API wachtwoord en moet meegegeven worden aan elke API-aanroep. Net als bij elk wachtwoord, is het van belang dat u de Key en Secret veilig bewaart en alleen deelt met anderen die u vertrouwt met uw gegevens.


4

2.3

API URL Alle REST API aanroepen hebben de volgende URL als basis: https://restapi.mailplus.nl/integrationservice-1.1.0/ N.B.: Deze URL werkt alleen als er een methode op de juiste manier wordt aangesproken.

2.4

API Methodes XML en JSON De API kan met zowel XML als JSON overweg. Bij het opsturen van gegevens, zal de header “Content-Type” gezet moeten worden met als waarde “application/xml” of “application/json” om respectievelijk XML of JSON op te sturen. Om te bepalen of de API XML of JSON teruggeeft, kan de header “Accept” worden gezet met als waarde respectievelijk “application/xml” of “application/json”. Standaard methode formaat Het standaard methode formaat van alle REST API verzoeken is: METHOD https://restapi.mailplus.nl/integrationservice-1.1.0/ transaction?parameters Methode GET, POST, PUT, of DELETE Transaction De API service die u wilt aanspreken, bijvoorbeeld “product”. Parameters (indien GET) De aanvullende parameters die mogelijk meegegeven kunnen worden aan een API-verzoek. Alle parameter waardes dienen URL-encoded te zijn. Ter illustratie: “spaties” dienen te worden omgezet naar “%20”. Veel gangbare programmeertalen, zoals Java, Javascript, en PHP hebben built-in functions die hiervoor kunnen zorgen.


5

Response De response van alle REST API aanroepen is JSON of XML. U kunt zelf bepalen wat u het prettigst vindt werken.

2.5

Foutafhandeling Indien er iets niet goed gaat, geeft de API-service een foutmelding terug in XML of JSON. U krijgt dan altijd een “errorType” en een “message” terug. Statuscode MailPlus geeft één van de volgende drie statuscodes terug bij een fout: 404: badrequest A given value was invalid (e.g. wrong e-mail address for a contact) 401: Unauthorized Wrong credentials (key and secret) given 404: Not found The given resource does not exists (e.g. when doing an update on a contact which does not exists in MailPlus) Hieronder enkele voorbeelden. Voorbeeld 1: Verkeerde paramater meegestuurd Hieronder een voorbeeld van een foutmelding die u terugkrijgt indien u een verkeerde parameter heeft meegestuurd. In dit geval een verkeerde productprijs. XML

<errorResponse>

<errorType>INVALID_PARAMS

<message>price invalid


6

JSON

{“errorType”:”INVALID_PARAMS”,

“message”:”price invalid”}

Voorbeeld 2: Product bestaat niet Hieronder een voorbeeld van een foutmelding die u terugkrijgt indien u een product probeert te wijzigen of te verwijderen waarvan het productId niet bestaat. De response code = 404. XML

<errorResponse>

<errorType>PRODUCT_NOTFOUND

<message>product not found with externalProductId:

test1355147847647123

JSON

2.6

{“errorType”:”PRODUCT_NOTFOUND”,

“message”:”product not found with externalProductId: test1355147847647123”}

Maak gebruik van een wachtrij Er kan altijd iets mis zijn met de verbinding tussen de webwinkel en MailPlus eCom. Dit kan verschillende oorzaken hebben. Bijvoorbeeld omdat de server waar de webwinkel op draait tijdelijk geen internetverbinding heeft. Het is verstandig om hier rekening mee te houden bij het ontwikkelen van een connector.

Hoe werkt het wachtrijprincipe? De connector moet altijd eerst gewoon een REST API methode aanroepen op het moment dat het er toe doet. Pas als dat niet gelukt is, omdat er iets mis is met de verbinding tussen de webwinkel en MailPlus eCom, dan moet de aanroep automatisch worden opgeslagen in een


7

wachtrij. Op deze manier is de connector in staat om nieuwe pogingen te doen om de aanroep alsnog te laten lukken. Het heeft geen zin om dit in de eeuwigheid te blijven proberen als er iets structureel mis is met verbinding. Het advies is om het een beperkt aantal keer opnieuw te proberen met een oplopende interval. Dus bijvoorbeeld de eerste keer na 1 minuut, dan na 5 minuten, dan na 10 minuten, dan na een uur, et cetera. De wachtrij wordt op chronologische volgorde afgewerkt. Het is raadzaam om de wachtrij van mislukte aanroepen in een overzicht te tonen in het backend van de webwinkel. Dan is achteraf zichtbaar of er mislukte aanroepen zijn geweest en welke dat waren. Als een aanroep bij een herhaalpoging alsnog gelukt is, mag deze uit het overzicht verdwijnen.


8

3

Contacten synchroniseren De webwinkel is het leidende systeem voor contactgegevens. Nieuwe inschrijvingen voor de nieuwsbrief of nieuwe klanten ontstaan in de webwinkel. Voor een marketeer die MailPlus eCom gebruikt voor het versturen van nieuwsbrieven is het fijn als het contactenbestand altijd up-to-date is op het moment dat de nieuwsbrief de deur uit moet. Daarom is het wenselijk om contacten (near-) real-time te synchoniseren naar MailPlus eCom.

3.1

Welke contacteigenschappen worden gesynchroniseerd? Er zijn een aantal contactvelden standaard beschikbaar in MailPlus eCom, zoals Voor- en Achternaam, E-mailadres, et cetera. Om precies te weten welke velden dit zijn kunt u het beste gebruikmaken van een REST API methode die deze velden ophaalt. Als resultaat krijgt u niet alleen de veldnamen te zien, maar ook de formaten waarin deze dienen te worden opgeslagen. Twee contactvelden verdienen speciale aandacht: 1. firstPurchaseDate 2. lastPurchaseDate Op basis van deze gegevens kunnen er automatische campagnes ingesteld worden in MailPlus eCom. Ook deze gegevens worden gevoed door de webwinkel. De firstPurchaseDate wordt eenmalig gezet op het moment dat iemand voor de allereerste keer een bestelling plaatst. De lastPurchaseDate dient elke keer door de webwinkel aangepast te worden op het moment dat iemand een bestelling plaatst.

3.2

Permissies In MailPlus eCom wordt gebruikgemaakt van permissies. Dat wil zeggen dat een contact zich kan inschrijven of juist afmelden voor een specifieke e-mailing. Standaard bestaan er twee permissies in MailPlus eCom, te weten: “Nieuwsbrief” en “Speciale acties voor klanten”. De


9

permissie “Nieuwsbrief” spreekt voor zich. De permissie “Speciale acties voor klanten” is bedoeld voor de event-driven marketing campagnes. Om een voorbeeld te geven, iemand die zich afmeldt voor Product review mailings, wil misschien best de nieuwsbrief blijven ontvangen. Door gebruik te maken van permissies is dat mogelijk.

3.3

Contact toevoegen aan MailPlus eCom Als er een nieuw contact ontstaat in de webwinkel, dan kan deze direct worden ingeschoten in MailPlus eCom via de REST API. Nieuwe contacten kunnen ontstaan door nieuwsbriefinschrijvingen of door klantregistraties. Het kan ook een combinatie van beide zijn.

3.4

Contact wijzigen in MailPlus eCom In de webwinkel kunnen er diverse plekken zijn waar contactgegevens wijzigen. Bijvoorbeeld door de webwinkelier in het backend of door contacten (klanten) zelf op een profielpagina als zij ingelogd zijn in het frontend van de webwinkel. Zodra er een contactwijziging plaatsvindt, dient de wijziging direct doorgegeven te worden aan MailPlus eCom. Er zijn twee methodes om contacten in MailPlus eCom te wijzigen. Door middel van de methode om contacten toe te voegen waarbij “update” op “true” wordt gezet. Deze methode wordt aanbevolen, want dan hoeft de webwinkel niet te onthouden of een contact mogelijk al eens eerder is ingeschoten. De andere methode is specifiek voor het wijzigen van een contact.

3.5

Contact verwijderen uit MailPlus eCom Het is niet mogelijk om contacten te verwijderen uit MailPlus eCom. Zo blijft de historie van e-mailings uit het verleden in tact. Bovendien is het van belang dat hard bounces en afmeldingen blijven bestaan in MailPlus eCom om te voorkomen dat iemand ten onrechte alsnog nieuwe e-mailings ontvangt. Als een contact wordt verwijderd in de webwinkel, dan dienen alle permissies van dat contact uitgezet te worden in MailPlus eCom door het contact te wijzigen.


10

4

Wijzigingen, afmeldingen en bounces In principe is de webwinkel leidend voor alle contactgegevens. Maar er zijn een paar uitzonderingen voor zaken die plaatsvinden in MailPlus eCom. Het gaat om de volgende zaken: • O ntvangers van een e-mailing die hun gegevens wijzigen op een landingspagina in MailPlus eCom. • Ontvangers van een e-mailing die zichzelf afmelden. • Ontvangers van een e-mailing waarvan het e-mailadres is gebounced. Deze zaken dienen periodiek te worden opgehaald door de webwinkel om de gegevens in de webwinkel up-to-date te houden.

4.1

Wijzingen ophalen uit MailPlus eCom Elke e-mailing die wordt verstuurd vanuit MailPlus eCom heeft een link in het bericht opgenomen waarmee de ontvanger zijn of haar contactgegevens kan wijzigen op een landingspagina in MailPlus eCom.

In principe kunnen dat alle gegevens zijn die bekend zijn van dat contact in MailPlus eCom. Als het e-mailadres tevens wordt gebruikt in de webwinkel als gebruikersnaam om in te loggen als klant, dan is het raadzaam om dit veld niet op te nemen in het formulier op de


11

profielwijzigpagina in MailPlus eCom. Als ontvangers hun e-mailadres willen wijzigen, dan dienen ze dat te doen in de webshop. Contactwijzigingen uit MailPlus eCom dienen periodiek te worden opgehaald door de webwinkel. Bijvoorbeeld één keer per uur of één keer per dag. Bij de methode om contactgegevens op te halen dient de webwinkel een start- en eindtijd van de afgelopen periode mee te sturen sinds de vorige ophaalactie. Het is daarbij raadzaam om een marge van minstens 10 minuten aan te houden tussen het moment van ophalen en de eindtijd van de periode. Als die tijden precies gelijk gehouden zouden worden, dan bestaat er de mogelijkheid dat er wijzigingen gemist worden.

4.2

Afmeldingen ophalen uit MailPlus eCom Elke e-mailing die wordt verstuurd vanuit MailPlus eCom heeft een link in het bericht opgenomen waarmee de ontvanger zichzelf kan afmelden voor toekomstige e-mailings van gelijke soort. In feite is een afmelding hetzelfde als een contactwijziging, omdat een afmelding een verandering betekent van één of meerdere permissies van het contact. Het permissie-veld van een contact is niet anders dan andere contactvelden. Daarom kunnen afmeldingen met dezelfde methode als het ophalen van wijzigingen periodiek worden opgehaald door de webwinkel.

4.3

Bounces ophalen uit MailPlus eCom Bij iedere e-mailing die wordt gedaan in MailPlus eCom kunnen er bounces ontstaan. De e-mail is dan niet bij de desbetreffende ontvanger aangekomen.


12

Bij een soft bounce is er sprake van een tijdelijke situatie. Hier hoeft de webwinkel niets mee te doen. Als er sprake is van een hard bounce, dan is het e-mailadres van het desbetreffende ontvanger niet in orde. Het kan gaan om een typefout of het e-mailadres bestaat gewoonweg niet meer. Hard bounces dienen periodiek door de webwinkel opgehaald te worden uit MailPlus eCom. In de eerste plaats om het bestand in de webwinkel schoon te houden en in de tweede plaats om er eventueel een vervolgactie aan te koppelen. Bijvoorbeeld het nabellen van de desbetreffende klant. Eventueel kunt u een melding tonen aan de consument bij de eerstvolgende keer dat hij of zij is ingelogd in de webwinkel. Ook bij de methode om bounces op te halen dient de webwinkel een start- en eindtijd van de afgelopen periode mee te sturen sinds de vorige ophaalactie. En ook daarbij is het raadzaam om een marge van minstens 10 minuten aan te houden tussen het moment van ophalen en de eindtijd van de periode. Als die tijden precies gelijk gehouden zouden worden, dan bestaat er de mogelijkheid dat er wijzigingen gemist worden.


13

5

Producten Synchroniseren In MailPlus eCom kan een marketeer eenvoudig producten uit de webwinkel plaatsen in een nieuwsbrief. Producten zijn met een simpele klik in de juiste opmaak in de nieuwsbrief zonder dat daar technische kennis voor nodig is.

Daarvoor is het wel nodig om alle producten uit de webwinkel real-time te synchroniseren naar MailPlus eCom. De producten uit de webwinkel verschijnen in een popup binnen de editor. Van daaruit kunnen de producten met een simpele klik in de nieuwsbrief geplaatst worden.


14

5.1

Producteigenschappen De volgende eigenschappen van een product kunnen worden ingeschoten in MailPlus eCom. • • • • • • • • • • • • • • • • • •

Brand (merknaam) Productnaam Omschrijving (kort) VanPrijs (de prijs zonder korting) Prijs Categorie Url naar de productafbeelding in de webwinkel (afmeting 1) Url naar de productafbeelding in de webwinkel (afmeting 2) Url van de rating-afbeelding (hoeft niet gebruikt te worden) Voorraad (Goed of Beperkt) Specificaties (een lijst van één of meerdere producteigenschappen) Cijfer productwaardering Taal van het product Link naar de productpagina in de webwinkel Link naar de review-pagina van het product Link die het product toevoegt aan de winkelwagen Gtin Sku


15

5.2

Product toevoegen aan MailPlus eCom Als er een nieuw product ontstaat in de webwinkel, dan dient deze direct te worden ingeschoten in MailPlus eCom via de REST API.

5.3

Product wijzigen in MailPlus eCom Als een product wordt gewijzigd in de webwinkel, dan dient deze wijziging direct ook in MailPlus eCom te worden doorgevoerd. Houd er rekening mee dat als een product wordt gereviewed door een consument in de webwinkel, dat dat ook een productwijziging betekent, namelijk een wijziging van de rating-waarde.

5.4

Product verwijderen uit MailPlus eCom Als een product wordt verwijderd in de webwinkel, dan dient deze direct ook uit MailPlus eCom te worden verwijderd.


16

6

Orders synchroniseren Als alle orders in de webwinkel worden gesynchroniseerd naar MailPlus eCom, dan kan een marketeer op basis van deze gegevens segmenteren in MailPlus eCom. Zo kan men bijvoorbeeld een gerichte e-mailing sturen naar alle mensen die in een bepaalde periode een bepaald product hebben gekocht.

6.1

Ordereigenschappen De volgende eigenschappen van een order kunnen worden ingeschoten in MailPlus eCom. • • • •

OrderId (unieke referentie uit de webwinkel) Orderdatum (moment dat de order wordt geplaatst) Unieke id van de contactpersoon Product(en) van de order (alleen producten die gesynchroniseerd zijn) • Totale orderbedrag (in centen)

6.2

Order toevoegen aan MailPlus eCom Als er een nieuwe order ontstaat in de webwinkel, dan dient deze direct of indirect te worden ingeschoten in MailPlus eCom via de REST API.

6.3

Order wijzigen in MailPlus eCom Als een order wordt gewijzigd in de webwinkel, dan dient deze wijziging direct of indirect ook in MailPlus eCom te worden doorgevoerd.

6.4

Order verwijderen uit MailPlus eCom Als een order wordt verwijderd (geannuleerd) in de webwinkel, dan dient deze direct of indirect ook uit MailPlus eCom te worden verwijderd.


17

7

Conversie doorgeven MailPlus eCom heeft uitgebreide mailingrapportages. Daarin kan onder andere worden getoond wat de directe conversie is geweest in de webwinkel naar aanleiding van de verzonden e-mailing. Daarnaast zijn er trendrapportages te zien, zodat de marketeer over een langere periode kan zien of de effectiviteit van zijn e-mailings toeneemt of afneemt.

Er zijn twee soorten conversies die door de webwinkel naar MailPlus eCom kan worden doorgegeven: 1. D e ontvanger van de e-mail maakt een nieuwe winkelwagen aan. 2. De ontvanger van de e-mail rondt een bestelling af.


18

7.1

Conversie winkelwagen aangemaakt doorgeven Op het moment dat een contactpersoon die vanuit een nieuwsbrief heeft geklikt een eerste product toevoegt aan de winkelwagen in de webwinkel, dient er door de webwinkel een signaal gegeven te worden aan MailPlus eCom. Voor de rapportages in MailPlus eCom is het van belang om te weten wie die contactpersoon is geweest. Dit is opgelost door met iedere link vanuit de e-mail naar de webwinkel een parameter mee te sturen met een bepaalde code (MailPlusId). Deze code dient te worden opgevangen door de webwinkel zodra de ontvanger van de e-mail in de webwinkel is aanbeland. De code dient door de webwinkel in de sessie bewaard te worden, zodat op het moment dat de conversie plaatsvindt deze code samen met de datum/tijd meegestuurd kan worden naar MailPlus eCom.

7.2

Conversie bestelling geplaatst doorgeven Op het moment dat een contactpersoon die vanuit een nieuwsbrief heeft geklikt een het bestelproces inclusief betalen volledig heeft doorlopen in de webwinkel, dient er door de webwinkel een signaal gegeven te worden aan MailPlus eCom.


19

Voor de rapportages in MailPlus eCom is het niet alleen van belang om te weten wie die contactpersoon is geweest, maar ook wat het totale orderbedrag is geweest en welke producten ermee gemoeid waren. Deze gegevens dienen naast de datum/tijd en de code uit MailPlus eCom, meegestuurd te worden met het conversie-signaal naar MailPlus eCom.


20

8

Automatische campagnes MailPlus eCom kent een aantal klant-en-klare automatische campagnes waarvan een deel door de webwinkel aangeroepen kunnen worden. Het gaat om campagnes die door het gedrag van de klant in de webwinkel automatisch worden aangestuurd.

De volgende campagnes worden standaard geleverd bij een MailPlus eCom account: 1. 2. 3. 4. 5.

Welkomscampagne bij nieuwe nieuwsbriefaanmelding Verlaten winkelwagencampagne Product reviewcampagne Verjaardagscampagne Win Back campagne

De eerste 3 campagnes worden direct door de webwinkel getriggerd voor een bepaalde contactpersoon. Alleen de webwinkel weet het moment waarop dat gebeurt. De verjaardagscampagne wordt vanuit MailPlus eCom getriggerd op basis van de geboortedatum die met de contactgegevens worden gesynchroniseerd. De win back campagne wordt ook vanuit MailPlus eCom getriggerd op basis van de laatste aankoopdatum die met de contactgegevens worden gesynchroniseerd.


21

8.1

Welkomstcampagne bij aanmelding nieuwsbrief Op het moment dat een contactpersoon zich aanmeldt voor de nieuwsbrief in de webwinkel, dient het contact niet alleen toegevoegd te worden aan MailPlus eCom, maar direct erna kan er voor dat contact een automatische welkomstcampagne getriggerd worden. Vanuit de campagne wordt er dan een welkomstbericht gestuurd naar de nieuwe aanmelder. Houd er rekening mee dat aanmelden voor de nieuwsbrief in een webwinkel vaak op diverse plekken kan gebeuren: een apart formulier of een checkbox bij het het bestelproces, etc.

8.2

Verlaten winkelwagen campagne Als in de webwinkel kan worden geregistreerd dat iemand een winkelwagen heeft aangemaakt, zonder uiteindelijk te hebben afgerekend, dan is het mogelijk om op dat moment voor dat contact een verlaten winkelwagen campagne te triggeren. Er zijn talloze redenen waarom iemand een winkelwagen achterlaat zonder af te rekenen. Soms gaat het om een technische storing, bijvoorbeeld in het betaalproces. Soms gaat het om een probleem met de internetverbinding. Soms gaat het om iemand die gewoon zijn browser heeft afgesloten. Bij het triggeren van een campagne kunnen door de webwinkel gegevens worden meegestuurd die automatisch geplaatst kunnen worden in het e-mailbericht wat uiteindelijk wordt verstuurd. Denk daarbij aan producten, links, vouchers, et cetera. Deze gegevens worden “campaignFields” genoemd en hebben een naam, één of meerdere waardes en soms een type. Zo is het bij de verlaten winkelwagencampagne nuttig om in het e-mailbericht de producten te tonen die in de winkelwagen zaten op het moment dat die werd achtergelaten. Ook is het mogelijk om een link mee te sturen naar de verlaten winkelwagen, zodat een ontvanger van de e-mail alsnog zijn winkelwagen kan afrekenen zonder hem opnieuw te hoeven samenstellen.


22

Productgegevens tonen in een campagnebericht Omdat alle productgegevens al real-time synchroon gehouden worden met MailPlus eCom, hoeven de productgegevens niet opnieuw meegestuurd te worden bij het triggeren van de campagne. De unieke productId’s zijn voldoende. Het template in MailPlus eCom bepaalt welke productgegevens getoond worden in het campagnebericht. Om de campagne zonder extra handelingen meteen te laten werken in MailPlus eCom, is het nodig om de juiste naamgeving te hanteren bij naam en type: • naam = “productlist” • type = “PRODUCTLIST” (in hoofdletters) Link naar winkelwagen tonen in campagnebericht Ook de link naar de verlaten winkelwagen kan automatisch geplaatst worden in het campagnebericht. Om de campagne zonder extra handelingen meteen te laten werken in MailPlus eCom, is het nodig om de juiste naamgeving te hanteren bij naam: • naam = “linktocart”

8.3

Product review campagne Een product review campagne houdt in, dat iemand na enige tijd na de bestelling automatisch een e-mail krijgt waarin hem of haar wordt gevraagd om een review te geven op het bestelde product(en). Ook deze campagne wordt aangestuurd vanuit de webwinkel. Dat is niet op het moment dat iemand een order heeft geplaatst, maar op het moment dat de order in het backend van de webwinkel op status “verzenden” wordt gezet door de webwinkelier. Je wilt namelijk voorkomen dat iemand een product review e-mail krijgt, terwijl het product nooit is verzonden. Productgegevens tonen in campagnebericht Ook in het campagnebericht van de product review campagne kunnen automatisch de producten geplaatst worden die onderdeel waren van de order. Lees bij de verlaten winkelcampagne hoe je producten kunt plaatsen in een campagnebericht.


23

9

Referentie REST API methodes

9.1

Methode: Contact toevoegen Met deze methode is het mogelijk om een contact aan MailPlus toe te voegen. Methode POST URL https://restapi.mailplus.nl/integrationservice-1.1.0/contact U kunt op twee manieren de content doorgeven: Content-Type: application/xml

<externalId>123

false

<properties>

<list1>

<entry bit=”1”>true


<email>[email protected]

Voornaam

false

false


24

Content-Type: application/json

{

“update”:false,

“purge”:false,

“contact”:{

“externalId”:”123”,

“testGroup”:false,

“properties”:{

“list1”:[

{“bit”:1,”enabled”:true},

{“bit”:2,”enabled”:true}],

“email”:”[email protected]”,

“firstName”:”Voornaam”

}

}

}

Parameters Een ContactRequest bestaat uit: • u pdate: boolean Als het contact al bestaat en update is true dan wordt het contact bijgewerkt. Indien false dan komt er een foutmelding terug als het contact al bestaat • purge: boolean Indien het contact wordt bijgewerkt dan worden properties die NIET zijn gezet geleegd. • Contact Een Contact object. Een Contact object bestaat uit: • e xternalId Het unieke id van dit contact • testGroup: boolean Als dit true is dan wordt het contact ook toegevoegd aan de testgroep in MailPlus.


25

• P roperties De properties die gezet moeten worden. Zie methode voor het ophalen van de properties (hoofdstuk 9) voor meer details. • Datumnotatie Geboortedatum en andere datums hebben formaat yyyyMM-dd. Datum-tijd velden hebben het formaat yyyy-MMddThh:mm:ss. De timezone (+02:00) is optioneel. Response Als response geeft de REST API service een http-statuscode “204” terug. Dit betekent dat het contact is succesvol is toegevoegd aan MailPlus.

9.2

Methode: Contact wijzigen Met deze methode is het mogelijk om een contact in MailPlus te wijzigen. Methode PUT URL https://restapi.mailplus.nl/integrationservice-1.1.0/contact/{externalId} U kunt op twee manieren de content doorgeven: Content-Type: application/xml

<externalId>123

false

<properties>

<list1>




Voornaam

false


26

Content-Type: application/json {

“purge”:false,

“contact”:{

“externalId”:”123”,

“testGroup”:false,

“properties”:{

“list1”:[

{“bit”:1,”enabled”:true},

{“bit”:2,”enabled”:true}

],

“email”:”[email protected]”,

“firstName”:”Voornaam”

},

}

}

Parameters Een ContactRequest bestaat uit: • p urge: boolean Indien het contact wordt bijgewerkt, dan worden properties die NIET zijn gezet geleegd. • contact Een Contact object. Een Contact object bestaat uit: • externalId Het unieke id van dit contact. • testGroup: boolean Als dit true is dan wordt het contact ook toegevoegd aan de testgroep in MailPlus. • Properties De properties die gezet moeten worden. Zie methode getAvailableProperties voor meer details.


27

Response Als response geeft de REST API service een http-statuscode “204” terug. Dit betekent dat het contact is succesvol is gewijzigd in MailPlus.

9.3

Methode: Contact ophalen Met deze methode is het mogelijk om de gegevens van een contact uit MailPlus op te halen. Methode GET URL https://restapi.mailplus.nl/integrationservice-1.1.0/contact/{externalId} Parameters Een contact bestaat uit: • externalId: string • create Aanmaak datum. Een timestamp in JSON, ISO 8601 formaat in XML • encryptedId: string. Het unieke ID van MailPlus. • lastChanged Laatst gewijzigde datum. Een timestamp in JSON, ISO 8601 formaat in XML • temporary: Boolean Geeft aan of het een tijdelijk contact is • properties Een lijst van properties van het contact. Wat hier in kan staan is afhankelijk van de call om alle beschikbare properties op te halen (getAvailableProperties) • channels Alle beschikbare kanalen voor het contact: EMAIL, DM (direct mail) en SMS. De waarde geeft aan of dit contact beschikbaar is voor het betreffende kanaal.


28

Response Als response geeft de REST API service het contactobject terug met alle gevulde contacteigenschappen. Voorbeeld XML response:

false

true

false

<encryptedId>UZ8I5rBSIqtGVKe

<externalId>123

2009-06-26T10:06:16+02:00

<properties>

Achternaam

Klant,

2013-01-22

MailPlus

Amsterdam


<entry bit=”1” description=”nieuwsbrief”>false

<entry bit=”2” description=”servicebrief”>true

false

true


29

Voorbeeld XML response: {

"externalId" : "13",

"created" : 1246003576000,

"encryptedId" : "UZ8I5rBSIqtGVKe",

"testGroup" : true,

"lastChanged" : 1246003576000,

"temporary" : false,

"properties" : {

"lastName" : "Achternaam",

"freeField1" : "Klant,",

"datum1" : "2013-01-22",

"organisation" : "MailPlus",

"city" : "Amsterdam",

"email" : "[email protected]",

"permissions":[

{"description":"nieuwsbrief","bit":1,"enabled":false},

{"description":"servicebrief","bit":2,"enabled":true}

]

},

"channels" : [

{"name" : "DM","value" : false},

{"name" : "EMAIL","value" : true},

{"name" : "SMS",

"value" : false}

]

}


30

9.4

Methode: Gewijzigde contacten ophalen Met deze methode is het mogelijk om alle contacten uit MailPlus op te halen die in een bepaalde periode zijn gewijzigd. Methode GET URL https://restapi.mailplus.nl/integrationservice-1.1.0/contact/updates/list Parameters Parameters: • toDate Verplicht. ISO 8601 datum formaat (2013-0101T13:14:00+02:00). De timezone (+02:00) is optioneel • fromDate Verplicht. ISO 8601 datum formaat (2013-0101T13:14:00+02:00). De timezone (+02:00) is optioneel Response Als response geeft de REST API service een lijst van contactobjecten terug met alle gevulde contacteigenschappen. Voorbeeld XML response

false

true

false


<externalId>123

2009-06-26T10:06:16+02:00

<properties>

Achternaam


31

Klant,

2013-01-22

MailPlus

<externalId>123

Amsterdam


<entry bit=”1” description=”nieuwsbrief”>false

<entry bit=”2” description=”servicebrief”>true

false

true

Voorbeeld JSON response

[{

“externalId” : “13”,

“created” : 1246003576000,

“encryptedId” : “UZ8I5rBSIqtGVKe”,

“testGroup” : true,

“lastChanged” : 1246003576000,

“temporary” : false,

“properties” : {

“lastName” : “Achternaam”,

“freeField1” : “Klant,”,

“datum1” : “2013-01-22”,

“organisation” : “MailPlus”,


“city” : “Amsterdam”,

“mailType” : “direct”,

“email” : “[email protected]”,

“permissions”:[

{“description”:”nieuwsbrief”,”bit”:1,”enabled”:false},

{“description”:”servicebrief”,”bit”:2,”enabled”:true}

]

},

“channels” : [


32

{“name” : “DM”,“value” : false},

{“name” : “EMAIL”,“value” : true},

{“name” : “SMS”,“value” : false}

9.5

]

}]

Methode: Gebouncede contacten ophalen Met deze methode is het mogelijk om alle contacten uit MailPlus op te halen die in een bepaalde periode zijn gebounced. Methode GET URL https://restapi.mailplus.nl/integrationservice-1.1.0/contact/bounces/list Parameters Parameters: • toDate Verplicht. ISO 8601 datum formaat (2013-0101T13:14:00+02:00). De timezone (+02:00) is optioneel • fromDate Verplicht. ISO 8601 datum formaat (2013-0101T13:14:00+02:00). De timezone (+02:00) is optioneel Een contactBounce bestaat uit: • contact Het contact waarvoor de bounce is opgetreden • date De datum wanneer de bounce is opgetreden • type HARDBOUNCE of SOFTBOUNCE • encryptedActId Het encrypted activityId (de mailing) waarvoor de bounce is opgetreden (voor toekomstig gebruik)


33

Response Als response geeft de REST API service een lijst van contactobjecten terug met alle gevulde contacteigenschappen. Voorbeeld XML reponse:

false

true

false


<externalId>123

2009-06-26T10:06:16+02:00

<properties>

Achternaam

Klant,

2013-01-22

MailPlus

<externalId>123

Amsterdam


<entry bit=”1” description=”nieuwsbrief”>

false

<entry bit=”2” description=”servicebrief”>

true

false

true

2013-01-29T13:48:54+01:00

HARDBOUNCE


34

<encryptedActId>Hr92crXz5A5z8AN

false

true

false


<externalId>123

2009-06-26T10:06:16+02:00

<properties>

Achternaam

Klant,

2013-01-22

MailPlus

<externalId>123

Amsterdam


<entry bit=”1” description=”nieuwsbrief”>

false

<entry bit=”2” description=”servicebrief”>

true

false

true

2013-01-29T13:48:54+01:00

SOFTBOUNCE

<encryptedActId>Hr92crXz5A5z8AN


35

Voorbeeld JSON response

[{

“date” : 1359463734000,

“type” : “HARDBOUNCE”,

“contact” : {


“created” : 1246003576000,



“lastChanged” : 1246003576000,





“datum1” : “2013-01-22”,

“organisation” : “Blinker”,





“permissions”:[



]

}

“channels” : [




]

},

“encryptedActId” : “Hr92crXz5A5z8AN”

},

{

“date” : 1359463734000,

“type” : “SOFTBOUNCE”,

“contact” : {


“created” : null,


36



“lastChanged” : 1246003576000,





“datum1” : “2013-01-22”,

“organisation” : “Blinker”,





“permissions”:[



]

},

“channels” : [




]

},

“encryptedActId” : “Hr92crXz5A5z8AN”

}]


37

9.6

Methode: Contacteigenschappen ophalen Met deze methode is het mogelijk om een lijst van contacteigenschappen (properties) uit MailPlus op te halen. Met deze methode bent u in staat om te weten met welke eigenschappen u een contact kunt toevoegen aan MailPlus. Methode GET URL https://restapi.mailplus.nl/integrationservice-1.1.0/contact/properties/ list Parameters Een property bestaat uit: • name De naam van de property zoals deze gebruikt moet worden in andere calls • description De omschrijving van de property zoals de MailPlus gebruiker deze in MailPlus ziet • type Het type van de property (string, set, date, birthdate, email, mobNr, gender, valuta, number) • entries Dit is alleen aanwezig indien het type “set” is. Hierin bevindt zich een lijst van de verschillende opties uit de set. Deze bestaat uit een bit en een description. De bit is de unieke identifier die gebruikt dient te worden bij een insert of een update van een contact.


38

Response Als response geeft de REST API service een lijst van properties terug. Voorbeeld XML response

<properties>

<property description=”E-mailadres” name=”email” type=”email” />

<property description=”Voornaam” name=”firstName” type=”string” />

<property description=”Achternaam” name=”lastName” type=”string” />

<property description=”Geslacht” name=”gender” type=”gender” />

<property description=”Mobiel nr.” name=”mobileNumber” type=”mobNr” />

<property description=”Opties” name=”list1” type=”set”>

<entries>

<entry bit=”1” description=”SAP” rank=”1” />

<entry bit=”2” description=”VM ware” rank=”2” />

<entry bit=”4” description=”Coolgen” rank=”4” />

<entry bit=”8” description=”Java, J2EE” rank=”8” />

<property description=”Geboortedatum” name=”birthday” type=”birthdate” />

<property description=”valuta1” name=”valuta1” type=”money” />

Voorbeeld XML response

[{

“name” : “email”,

“description” : “E-mailadres”,

“type” : “email”

}, {

“name” : “firstName”,

“description” : “Voornaam”,

“type” : “string”

}, {

“name” : “lastName”,

“description” : “Achternaam”,

“type” : “string”

},{

“name” : “gender”,


39

“description” : “Geslacht”,

“type” : “gender”

}, {

“name” : “mobileNumber”,

“description” : “Mobiel nr.”,

“type” : “mobNr”

}, {

“name” : “list1”,

“description” : “Opties”,

“type” : “set”,

“entries” : [ {

“bit” : 1,

“description” : “SAP”,

“rank” : 1

}, {

“bit” : 2,

“description” : “VM ware”,

“rank” : 2

}, {

“bit” : 4,

“description” : “Coolgen”,

“rank” : 4

}, {

“bit” : 8,

“description” : “Java, J2EE”,

“rank” : 8

}]

}, {

“name” : “birthday”,

“description” : “Geboortedatum”,

“type” : “birthdate”

}, {

“name” : “valuta1”,

“description” : “valuta1”,

“type” : “money”

}]


40

9.7

Methode: Product toevoegen Met deze methode is het mogelijk om een product uit de webshop toe te voegen aan MailPlus. Methode POST URL https://restapi.mailplus.nl/integrationservice-1.1.0/product U kunt op twee manieren de content doorgeven: Content-Type: application/xml

<productRequest>

true

<product>

Merknaam

<description>Dit is een korte omschrijving van het product.

<externalId>test1355142017524

12345678

http://uwwebshop.nl/image.png

http://uwwebshop.nl/largeimage.png

http://uwwebshop.nl/productpagina

45678

<price>12345

Categorie van het product

Naam van het product

<stock>GOOD

http://uwwebshop.nl/imagerating.png

http://uwwebshop.nl/reviewlink

http://uwwebshop.nl/addtocartlink

<sku>VC123456789HU

4.6

Nederlands

<specifications>

<specification>

<description>Description1

1

Value1


41

<specification>


2

Value2


“update”:”true”,

“product”:{

“brand”:”Merknaam”,

“description”:”Dit is een korte omschrijving van het product.”,

“externalId”:”test1355142017524”,

“gtin”:”12345678”,

“imageUrl”:”http://uwwebshop.nl/image.png”,

“imageLargeUrl”:”http://uwwebshop.nl/largeimage.png”,

“link”:”http://uwwebshop.nl/productpagina”,

“oldPrice”:”45678”,

“price”:”12345”,

“ category”:”Categorie van het product”,

“ name”:”Naam van het product”,

“ratingImageUrl”:”http://uwwebshop.nl/imagerating.png”,

“stock”:”GOOD”,

“reviewLink”:”http://uwwebshop.nl/reviewlink”,

“addToCartLink”:”http://uwwebshop.nl/ addtocartlink “,

“sku”:”VC123456789HU”,

“ratingValue”:”4.6”,

“language”:”Nederlands”,

“specifications”: [

{“description”:”Description1”,”value”:”Value1”,”rank”:”1”},

{“description”:”Description2”,”value”:”Value2”,”rank”:”2”}

]

}

}


42

Parameters Met update true/false kunt u bepalen of er wel of niet automatisch een update van het product moet plaatsvinden, indien het product al bestaat in MailPlus met hetzelfde externalId. De price en oldPrice van een product dienen in centen te worden opgegeven. Price kan indien van toepassing ook de actieprijs zijn. Het externalId is een uniek productid van de webshop op basis waarvan de synchronisatie verloopt. Met de parameter stock kan aangegeven worden of de voorraad van het product “GOOD” is of “LIMITED”. Niet de actuele voorraad in aantal hoeft dus te worden gesynchroniseerd, maar alleen of deze goed of beperkt is. Op deze manier wordt het aantal transacties in de koppeling beperkt. Alleen als de voorraad onder een bepaald minimaal niveau komt, dient de status “LIMITED” gesynchroniseerd te worden. Voor de marketeer in MailPlus eCom is dit interessant om te weten bij het plaatsen van producten in de nieuwsbrief. Eventueel zou ook de status “UNKNOWN” meegegeven kunnen worden. Het is ook mogelijk om een lijst van productspecificaties te synchroniseren. Dit is een lijst van één of meerdere producteigenschappen, waarbij elke eigenschap is opgebouwd uit een description, een value en eventueel een rank. Description en value zijn verplicht indien er een specificatie wordt gesynchroniseerd. Met rank kan worden bepaald in welke volgorde de specificaties worden getoond in een de nieuwsbrief. Hieronder in het rode kader een voorbeeld van productspecificaties.


43

De afmetingen van afbeeldingen (imageUrl en ratingImageUrl) moeten afgestemd zijn op de template van de nieuwsbrief. Gtin staat voor Global Trade Item Number (kan ook een EAN-nummer zijn). Sku staat voor Stock Keeping Unit, een gangbare productReferentie in webshops die niet hoeft te voldoen aan een standaard. De productReviewLink is een link naar een landingspagina (in de webshop) waar je als consument het product kunt reviewen. De volgende velden zijn verplicht: externalProductId, name, description, link, price en imageUrl. Response Als response geeft de REST API service een http-statuscode “204” terug. Dit betekent dat het product succesvol is toegevoegd aan MailPlus.

9.8

Methode: Product wijzigen Met deze methode is het mogelijk om een product in MailPlus te wijzigen. Methode PUT URL https://restapi.mailplus.nl/integrationservice-1.1.0/product/{externalId} U kunt op twee manieren de content doorgeven:


44

Content-Type: application/xml

<product>

Merknaam


12345678


http://uwwebshop.nl/largeimage.png


45678

<price>12345



<stock>GOOD




<sku>VC123456789HU

4.6

Nederlands

<specifications>

<specification>


1

Value1

<specification>


2

Value2


45


“brand”:”Merknaam”,

”description”:” Dit is een korte omschrijving van het product.”,

“gtin”:”12345678”,

”imageUrl”:”http://uwwebshop.nl/image.png”,

”imageLargeUrl”:”http://uwwebshop.nl/largeimage.png”,

”link”:”http://uwwebshop.nl/productpagina”,

”oldPrice”:”45678”,

”price”:”12345”,

”category”:” Categorie van het product”,

”name”:”Naam van het product”,

”stock”:”GOOD”,

“ratingImageUrl”:”http://uwwebshop.nl/imagerating.png”,

”reviewLink”:”http://uwwebshop.nl/reviewlink”,

”addToCartLink”:”http://uwwebshop.nl/addtocartink”,

”sku”:”VC123456789HU”,

”ratingValue”:”4.6”,

”language”:”Nederlands”,

”specifications”: [

{“description”:”Description1”,”value”:”Value1”,”rank”:”1”},

{“description”:”Description2”,”value”:”Value2”,”rank”:”2”}

]

}

Response Als response geeft de REST API service een http-statuscode “204” terug. Dit betekent dat het product is succesvol is gewijzigd in MailPlus.

9.9

Methode: Product verwijderen Met deze methode is het mogelijk om een product in MailPlus te verwijderen. Methode DELETE URL https://restapi.mailplus.nl/integrationservice-1.1.0/product/{externalId}


46

Response Als response geeft de REST API service een http-statuscode “204” terug. Dit betekent dat het product succesvol is verwijderd in MailPlus.

9.10

Methode: Product ophalen Met deze methode is het mogelijk om de gegevens van een product uit MailPlus op te halen. Methode GET URL https://restapi.mailplus.nl/integrationservice-1.1.0/product/{externalId} Parameters In de response zijn ook de changeDate en de creationDate van het product te zien. Response Als response geeft de REST API service het productobject terug met alle gevulde producteigenschappen. Voorbeeld

<product>

Merknaam


<externalId>test1355142017524

2013-01-17T11:53:50+01:00

2013-01-15T15:06:18+01:00

12345678



45678

<price>12345




47

<stock>GOOD




<sku>VC123456789HU

4.6

9.11

Methode: Order toevoegen Met deze methode is het mogelijk om een order uit de webshop toe te voegen aan MailPlus. Methode POST URL https://restapi.mailplus.nl/integrationservice-1.1.0/order U kunt op twee manieren de content doorgeven: Content-Typ: application/XML

<externalContactId>123

<externalId>test123

<externalProductIds>

<externalProductId>16


2013-04-25T11:15:53

123456

true


48

Conent-Type: application/JSON {

“order”:{

“externalId”:”test123”,

”externalContactId”:”123”,

”date”:”2013-04-25T11:15:53”,

”externalProductIds”:[“16”,”17”],

”value”:”782782”

},

“update”:true

}

Parameters Met update true/false kunt u bepalen of er wel of niet automatisch een update van de order moet plaatsvinden, indien de order al bestaat in MailPlus met hetzelfde externalId. Het externalContactId is de unieke referentie van de contactpersoon (klant) die de order heeft geplaatst in de webwinkel. Dit is een verplichte parameter en dient voor te komen in de database van MailPlus. Het externalId is de unieke referentie van de order in de webwinkel (orderId). Dit is een verplichte parameter. Met externalProductIds kunt u aangeven welke producten onderdeel waren van de order. U dient erop te letten dat u alleen id’s van producten meegestuurd die gesynchroniseerd zijn met MailPlus. Er dient minimaal één productId te worden meegestuurd. Date is de datum/tijd van het moment dat de order werd geplaatst door de klant. Dit is een verplichte parameter. De totale waarde van de order dient in centen te worden meegegeven in value. Dit is een verplichte parameter. Response Als response geeft de REST API service een http-statuscode “204” terug. Dit betekent dat de order succesvol is toegevoegd aan MailPlus.


49

9.12

Methode: Order wijzigen Met deze methode is het mogelijk om een order in MailPlus te wijzigen. Methode PUT URL https://restapi.mailplus.nl/integrationservice-1.1.0/order/{externalId} U kunt op twee manieren de content doorgeven: Content-Type: application/xml


<externalId>test123

<externalProductIds>



2013-04-25T11:15:53

123456

true

Content-Type: application/json { “order”:{ “externalId”:”test123”, ”externalContactId”:”123”, ”date”:”2013-04-25T11:15:53”, ”externalProductIds”:[“16”,”17”], ”value”:”782782” } }


50

Response Als response geeft de REST API service een http-statuscode “204” terug. Dit betekent dat de order succesvol is gewijzigd in MailPlus.

9.13

Methode: Order verwijderen Met deze methode is het mogelijk om een order in MailPlus te verwijderen. Methode DELETE URL https://restapi.mailplus.nl/integrationservice-1.1.0/order/{externalId} Response Als response geeft de REST API service een http-statuscode “204” terug. Dit betekent dat de order succesvol is verwijderd in MailPlus.

9.14

Methode: Winkelwagen aangemaakt doorgeven Met deze methode is het mogelijk om aan MailPlus door te geven dat er in de webshop een winkelwagen is aangemaakt naar aanleiding van een klik in de nieuwsbrief. Methode POST URL https://restapi.mailplus.nl/integrationservice-1.1.0/conversion U kunt op twee manieren de content doorgeven: Content-Type: application/xml


51

<mailplusId>cDsTpdQvmxZ34Py-mauTiawtXGDItMY-YRiVSdh7sbwxKcL

CREATE_SHOPPINGCART

2013-01-15T09:15:00+01:00


“mailplusId”:”cDsTpdQvmxZ34Py-mauTiawtXGDItMY-YRiVSdh7sbwxKcL”,

“type”:”CREATE_SHOPPINGCART”,

”interactionDate”:”2013-01-15T09:15:00+01:00”

}

Parameters Het mailplusId is het ID dat MailPlus zelf aan de webshop doorgeeft als iemand op een link in de e-mailing klikt. Zowel het mailplusId als type zijn verplicht om met de call mee te sturen. Het meesturen van de interactionDate is optioneel. Response Als response geeft de REST API service een http-statuscode “204” terug. Dit betekent dat het aanmaken van de winkelwagen succesvol is doorgegeven aan MailPlus.

9.15

Methode: Winkelwagen geconverteerd doorgeven Met deze methode is het mogelijk om aan MailPlus door te geven dat er in de webshop een winkelwagen is geconverteerd naar aanleiding van een klik in de nieuwsbrief. Dit betekent dat het hele besteltraject in de webshop inclusief de betaling is voltooid. Methode POST URL https://restapi.mailplus.nl/integrationservice-1.1.0/conversion U kunt op twee manieren de content doorgeven:


52

Content-Type: application/xml

<mailplusId>cDsTpdQvmxZ34Py-mauTiawtXGDItMY-YRiVSdh7sbwxKcL

<products>

<product>test1354791214013

<product>test1354791214553

CONVERT_SHOPPINGCART

236237

2013-01-15T09:15:00+01:00


“mailplusId”:”cDsTpdQvmxZ34Py-mauTiawtXGDItMY-YRiVSdh7sbwxKcL”,

”type”:”CONVERT_SHOPPINGCART”,

“value”:”236237”,

”products”:[

“test1354791214013”,

”test1354791214553”

]

}

Parameters Het mailplusId is het ID dat MailPlus zelf aan de webshop doorgeeft als iemand op een link in de e-mailing klikt. De totale waarde van de bestelling dient in centen te worden meegegeven in value. Zowel het mailplusId , type en value zijn verplicht om met de call mee te sturen. Het meesturen van products in de vorm van komma gescheiden externalProductId´s is optioneel. Ook het meesturen van de interactionDate is optioneel. Response


53

Als response geeft de REST API service een http-statuscode “204” terug. Dit betekent dat het converteren van de winkelwagen succesvol is doorgegeven aan MailPlus.

9.16

Methode: Alle campagnes ophalen Met deze methode is het mogelijk om alle campagnes van een MailPlusaccount op te halen. Methode GET URL https://restapi.mailplus.nl/integrationservice-1.1.0/campaign/list Response Als response geeft de REST API service een lijst terug van alle campagnes van het MailPlus-account. Per opgehaalde campagne krijg je de volgende gegevens terug: • e ncryptedId van de campagne (om de campagne op enig moment te kunnen stoppen indien nodig) • naam van de campagne • Alle externe triggers van de campagne, waarbij per trigger: o naam van de trigger o encryptedId van de trigger (om de campagne op enig moment te kunnen triggeren)


54

Voorbeeld XML:

true

<encryptedId>HE9Bs663Qm

Verlaten winkelwagen

<encryptedId>xjcUsjCbsq

trigger1

<encryptedId>6mC3rAtV4A

trigger2

Voorbeeld JSON:

[

{

“encryptedId”:” HE9Bs663Qm”,

”name”:” Verlaten winkelwagen”,

”active”:true,

”triggers”:[

{“encryptedId”:”xjcUsjCbsq”,”name”:”trigger},

{“encryptedId”:”6mC3rAtV4A”,”name”:”trigger 2”}

]

}

]


55

Bijzonderheden Ook inactieve campagnes kunnen worden opgehaald, zodat je deze alvast kunt instellen in het externe systeem. Alleen als er externe triggers in de campagne zijn geconfigureerd, krijg je deze mee in de response. Er is meestal maar een externe trigger per campagne ingesteld, maar het kunnen er meer zijn.

9.17

Methode: Campagne triggeren Met deze methode is het mogelijk om een MailPlus-campagne te triggeren voor een bepaald contact. Methode POST URL https://restapi.mailplus.nl/integrationservice-1.1.0/campaign/trigger/ {encryptedId} U kunt op twee manieren doorgeven voor welk contact de campagne getriggerd moet worden: Content-Type: application/xml

linktocart

http://uwwebshop.nl/verlatenwinkelwagen

test1355132700218

test1355136324672

productlist

PRODUCTLIST


56

vouchercode

12345



“campaignFields”:[

{

“name”:”linktocart”,

”value”:”http://uwwebshop.nl/verlatenwinkelwagen”

},

{

“values”:[

“test1355132700218”,

”test1355136324672”

],

“name”:”productlist”,

“type”:”PRODUCTLIST”

},

{

“name”:”vouchercode”,

”value”:”12345”

}

],

“externalContactId”:”123”

}

Parameters Het encryptedId is het ID van de campagnetrigger. Niet te verwarren met het ID van de campagne zelf. Response Als response geeft de REST API service een http-statuscode “204” terug. Dit betekent dat de campagne succesvol is getriggerd voor het contact in MailPlus.


57

9.18

Methode: Campagne stoppen Met deze methode is het mogelijk om een MailPlus-campagne te stoppen voor een bepaald contact. Methode POST URL https://restapi.mailplus.nl/integrationservice-1.1.0/campaign/ {encryptedId}/stop U kunt op twee manieren doorgeven voor welk contact de campagne gestopt moet worden: Content-Type: application/xml


Content-Type: application/json

{“externalContactId”:”123”}

Parameters Het encryptedId is het ID van de campagne. Niet te verwarren met het ID van de campagnetrigger. Response Als response geeft de REST API service een http-statuscode “204” terug. Dit betekent dat de campagne succesvol is gestopt voor het contact in MailPlus.


58

10

Aanvullende informatie Magento-connector voor MailPlus eCom Als u Magento gebruikt als e-comerce-platform, dan hoeft u niet zelf een koppeling met MailPlus eCom te ontwikkelen. Die heeft MailPlus al voor u laten ontwikkelen. Met de MailPlus-connector voor Magento worden contacten en producten real-time gesynchroniseerd. Daarnaast wordt conversie doorgegeven aan MailPlus, zodat in de rapportage van de e-mailing zichtbaar wordt welke ontvangers van de nieuwsbrief uiteindelijk iets hebben besteld en welke waarde dat vertegenwoordigd. Ten slotte kunt u event-driven marketing campagnes automatisch laten triggeren vanuit de webshop. Denk aan een welkomstcampagne voor een nieuwe klant of een verlaten winkelwagencampagne voor klanten die wel een winkelwagen hebben aangemaakt, maar uiteindelijk niet hebben afgerekend.


59

Webwinkel koppelen met MailPlus ecom via de REST API

Recommend Documents