MWW orders feed. Algemene orders feed in XML format

Transcriptie

1 MWW orders feed Algemene orders feed in XML format

2 Inhoudsopgave Algemeen... 3 Sleutel... 3 Versie... 3 URL... 3 Output... 3 Vragen?... 3 Changelog... 3 Veld definities... 4 Algemene informatie... 4 Orders... 5 Order... 5 Betaling... 5 Debiteur... 6 Adressen... 6 Orderregels... 7 Orderregel... 7 Artikelinformatie... 7 Kortingsinformatie... 8 Keuzelijstinformatie... 8 Prijs informatie... 8 Definitietabellen... 9 Betaalprovider... 9 Betaalmethode... 9 Orderstatus Ordertype GET parameters Foutmeldingen Pagina 2

3 Algemeen Sleutel Om gebruik te kunnen maken van de MWW orders feed heeft u een geldige sleutel nodig. Deze sleutel kan vanuit het Mijnwebwinkel beheer worden gegenereerd. Heeft u geen (geldige) sleutel neem dan contact op met de eigenaar van de webwinkel waarmee u een koppeling wilt maken. Versie Naast een geldige sleutel dient ook de versie van de feed meegegeven te worden via de GET parameter v. URL De URL voor de orders feed is De eigenaar van de webwinkel waarmee u een koppeling wilt maken kan u de volledige URL inclusief sleutel en versie verstrekken. N.B. Deze verbinding is via SSL beveiligd en alleen via beschikbaar. Output De output van de koppeling is in XML formaat. De gebruikte character encoding is UTF-8. Vragen? Heeft u vragen of opmerkingen m.b.t. de koppeling of documentatie? Neem dan contact met ons op via Selecteer bij onderwerp de optie technisch probleem / vraag. Changelog Overzicht van aanpassingen per versie. Versie Informatie 1.0 Eerste versie van de orders feed. 1.1 Wijziging in weergave van betaalmethode. Toevoeging BTW-nummer bij Factuuradres Waarde (id) van provider Mollie aangepast. Toevoeging van nieuwe betaalmethodes voor de providers Sisow en Mollie. Ogone heet voortaan Ingenico Attribuut id toegevoegd aan orderregels van het type article. Pagina 3

4 Veld definities In de tabellen hieronder staan per onderdeel de velden in de XML output beschreven. Algemene informatie Algemene informatie over de XML export Pad: mwwfeed Veldnaam Type Omschrijving [attribuut version ] string Versie van het export script. total_records integer Totaal aantal orders in de XML export. Default worden 10 orders getoond, dit is aan te passen via de GET parameter limit. Meer informatie hierover staat in het hoofdstuk GET parameters. Pagina 4

5 Orders Alle aanwezige orders in de XML export. Pad: mwwfeed->orders Order De details van elke order. Pad: mwwfeed->orders->order [attribuut number ] integer [ 11] Het ordernummer van de order. date date [yyyy-mm-dd] De datum van de order. time time [HH:ii:ss] De tijd van de order. description string [17] Tekstuele weergave: Order [ordernummer]. archived integer [1] Geeft aan of de order gearchiveerd is binnen het MWW beheer. 0 = niet gearchiveerd, 1 = gearchiveerd. status integer [1] De status van de order. De waarden staan gedefinieerd in de tabel Orderstatus. status_changed_date date [yyyy-mm-dd] De datum van wijzigen van de orderstatus. status_changed_time time [HH:ii:ss] De tijd van wijzigen van de orderstatus. payment Zie het onderdeel Betaling hieronder. weight float [11,3] Het totaal gewicht van de order (indien gedefinieerd per artikel) in kilogrammen. comment string [variabel] Een door de klant bijgevoegde opmerking. Betaling Informatie over de betaling, uitgesplitst in gebruikte provider, betaalmethode en de status. Pad: mwwfeed->orders->order->payment provider integer [2] De gebruikte betaalprovider. De waarden staan gedefinieerd in de tabel Betaalprovider. method integer [2] De gebruikte betaalmethode. De waarden staan gedefinieerd in de tabel Betaalmethode. status string [variabel] Tekstuele status van de betaling, indien beschikbaar. De tekst kan per gebruikte betaalmethode afwijken. Pagina 5

6 Debiteur De debiteur (klant) gegevens. Pad: mwwfeed->orders->order->debtor gender string [1] Het geslacht van de debiteur. name string [255] De naam van de debiteur. company string [255] De bedrijfsnaam van de debiteur. string [255] Het adres van de debiteur. phone string [15] Het telefoonnummer van de debiteur. bankaccount string [24] Het bankrekeningnummer van de debiteur. Adressen Het factuur- en bezorgadres van de debiteur. Indien het bezorgadres niet afwijkt van het factuuradres wordt het bezorgadres gevuld met dezelfde gegevens als het factuuradres. Pad: mwwfeed->orders->order->debtor->address [attribuut type ] string [7] Het type adres, waarde invoice of delivery. gender string [1] Het geslacht van de klant. name string [255] De naam van de klant. company string [255] De bedrijfsnaam van de klant. street string [255] De straatnaam van de klant. number string [10] Het huisnummer van de klant. zipcode string [10] De postcode van de klant. city string [100] De woonplaats van de klant. country string [255] Het land van de klant. taxnumber string [50] Het BTW nummer van de klant. Pagina 6

7 Orderregels Alle aanwezige orderregels. Pad: mwwfeed->orders->order->orderlines Orderregel De inhoud van een enkele orderregel. Het type van de orderregel staat in het attribuut type. Pad: mwwfeed->orders->order->orderlines->orderline [attribuut type ] string [8] Het type van de orderregel. De mogelijke waarden staan gedefinieerd in de tabel Ordertype. [attribuut id ] integer [11] Alleen van toepassing bij het type article. Bevat het interne ID van het artikel. description string [255] Tekstuele omschrijving van het type orderregel. Indien het type orderregel article betreft bestaat deze uit de naam van het artikel, aangevuld met eventuele gekozen opties (maat, kleur e.d.) en/of toegepaste actieprijs. price [attribuut tax ] float [15,6] float [2,2] Het totaalbedrag van de orderregel, excl. BTW. Het attribuut bevat het BTW percentage. Eventuele korting en/of meerprijs is in dit bedrag wel opgenomen. N.B. Orderregels van het type payment en discount kunnen meerdere BTW tarieven bevatten. In dat geval is per gebruikt BTW tarief een price veld aanwezig. quantity integer [16] Het totaal aantal van dit type. weight float [11,3] Het totaal gewicht van de orderregel. Artikelinformatie Indien de orderregel van het type article is bevat deze een element <article>. Pad: mwwfeed->orders->order->orderlines->orderline->article description string [255] Tekstuele omschrijving van het artikel price [attribuut tax ] float [15,6] float [2,2] De stuksprijs van het artikel, excl. BTW. Het attribuut bevat het BTW percentage Eventuele korting en/of meerprijs is in deze prijs niet meegenomen. Pagina 7

8 Kortingsinformatie Indien er een korting is toegepast op de orderregel staat dit vemeld in het element <discount>. Pad: mwwfeed->orders->order->orderlines->orderline->discount description string [255] Tekstuele omschrijving van de korting price [attribuut tax ] float [15,6] float [2,2] De stuksprijs van de korting, excl. BTW. Het attribuut bevat het BTW percentage. Het kortingsbedrag is een min-bedrag. Keuzelijstinformatie Indien bij een artikel één of meerdere opties uit keuzelijsten (bijv. maat of kleur) zijn opgegeven dan staan deze vermeld in het element <option>. Afhankelijk van het aantal gekozen opties kunnen er meerdere van deze elementen aanwezig zijn. Indien een gekozen optie een meerprijs t.o.v. de basisprijs van een artikel bevat dan wordt dit vermeld in het element <price>. Pad: mwwfeed->orders->order->orderlines->orderline->option description string [255] Tekstuele omschrijving van de gekozen optie price [attribuut tax ] float [15,6] float [2,2] De eventuele meerprijs van de gekozen optie t.o.v. de basisprijs van het artikel. Het attribuut bevat het BTW percentage. Prijs informatie Een overzicht van de totaalprijs van de order plus alle belastingbedragen per tarief. Pad: mwwfeed->orders->order->price total float [15,6] Het totaalbedrag van de order Dit bedrag is excl. BTW tax [ attribuut rate ] float [15,6] float [2,2] Het BTW bedrag van het betreffende tarief. Dit veld kan meerdere keren voorkomen, afhankelijk van de toegepaste BTW tarieven binnen de order. Pagina 8

9 Definitietabellen In onderstaande tabellen staan de definities vermeld welke verwijzen naar waarden gebruikt binnen de XML export. Betaalprovider De betekenis van de waarde in het veld mwwfeed->orders->order->payment->provider Waarde Provider 1 Mollie (oud) 2 Ingenico (Ogone) 3 MultiSafePay 4 Sisow 5 PayPal 6 AfterPay 7 Geen provider 8 Paytor 9 Mollie Betaalmethode De betekenis van de waarde in het veld mwwfeed->orders->order->payment->method Waarde Betaalmethode 1 ideal 2 SofortBanking / DIRECTebanking 3 Bancontact / MisterCash 4 Webshop Giftcard 5 Fijn Cadeaukaart 6 MasterCard 7 Visa 8 Creditcard 9 PayPal 10 Achteraf betalen 11 Rembours 12 Vooraf overmaken 13 Via factuur 14 Eénmalige machtiging 15 Automatische incasso 16 Betalen bij ophalen 17 Maestro 18 Podium Giftcard 19 Paysafecard 20 Bitcoins Pagina 9

10 Orderstatus De betekenis van de waarde in het veld mwwfeed->orders->order->status Waarde Betekenis 1 Bestelling in behandeling 2 Verzonden 3 Betaald 4 Geannuleerd 5 Klaar om af te halen 6 Betaald & afgehaald 7 Betalingsherinnering 8 Niet afgerond Ordertype De betekenis van de waarde in het attribuut van het veld mwwfeed->orders->order->orderlines->orderline Waarde article shipping discount payment Betekenis Informatie over een artikel Informatie over de verzendkosten Informatie over een kortingsbedrag / percentage Informatie over kosten voor een betaalmethode Pagina 10

11 GET parameters Standaard toont de feed de eerste 10 orders. Door middel van het meezenden van verschillende parameters kan er een selectie binnen de orders gemaakt worden. De parameters dienen als HTTP GET parameter meegezonden te worden. Voorbeeld: Om een export te genereren vanaf een bepaald ordernummer is de aanroep als volgt: Dit kan weer gecombineerd worden met een limit: Parameter Waarde Omschrijving v string De versie van de MWW feed. N.B. Deze parameter is verplicht. limit integer tussen 10 en 100 Het maximaal aantal orders wat opgevraagd kan worden via de XML export. offset integer Het recordnummer waar de XML export moet starten. Dit veld kan gecombineerd worden met de parameter limit. ordernumberoffset integer Het ordernummer waar de XML export moet starten. Dit veld kan gecombineerd worden met de parameter limit. ordernumber integer Opvragen van 1 enkele order o.b.v. het ordernummer. datestart dateend date format yyyy-mm-dd date format yyyy-mm-dd Offset vanaf een bepaalde datum. Dit veld kan gecombineerd worden met de parameters limit en date_end. Limit tot een bepaalde datum. Dit veld kan gecombineerd worden met de parameters limit en date_start. Pagina 11

12 Foutmeldingen Er kunnen verschillende foutmeldingen terugkomen, in onderstaande tabel staan de mogelijke meldingen en de redenen. Foutmeldingen worden via een http status header geserveerd. Melding Reden Oplossing Invalid version (http status: 400 Bad Request) Het versienummer van de feed is niet meegegeven of niet correct. Zorg ervoor dat de parameter v altijd meegegeven wordt, of controleer het versienummer. Invalid token (http status: 400 Bad Request) Inactive token (http status: 403 Forbidden) Expired token (http status: 403 Forbidden) Unknown token (http status: 403 Forbidden) De sleutel voldoet niet aan het aantal karakters van 64 of bevat vreemde karakters De sleutel is niet (meer) actief De sleutel is verlopen De sleutel is onbekend Controleer de sleutel op de juiste lengte en/of inhoud. Informeer bij de verstrekkende webwinkel. Informeer bij de verstrekkende webwinkel. Informeer bij de verstrekkende webwinkel. Pagina 12