Webshopkoppeling – API-documentatie
Met de Microcash-webshopkoppeling kun je artikelgegevens en voorraad ophalen en webshopbestellingen als factuur aanmaken in McWin, het kassasysteem van Microcash. Dit artikel is bedoeld voor ontwikkelaars die een webshop met Microcash verbinden.
De koppeling bestaat uit een dagelijks artikelbestand en een API voor actuele gegevens en factuuraanlevering. Voorraad opvragen en voorraad wijzigen zijn verschillende handelingen: /stock leest voorraad; voorraadmutaties via deze API ontstaan door het aanmaken van een factuur.
1. Benodigdheden en beschikbaarheid
- McWin draait op de servercomputer. Microcash verzorgt de installatie.
- McAppBridge is geïnstalleerd en actief. Microcash verzorgt de installatie.
- De bedrijfsgegevens zijn ingericht. Microcash maakt deze aan.
- Een API-loginaccount. Dit maak je aan in de Microcash Online Helpdesk-portal.
- Een API-Key en API-Code. Deze vind je in dezelfde portal.
- Toegang tot het artikelbestand. Microcash verstrekt de FTP-inloggegevens.
De servercomputer, McWin en McAppBridge moeten beschikbaar zijn zolang je livegegevens wilt opvragen of facturen wilt aanleveren. Als een van deze onderdelen niet beschikbaar is, kunnen aanvragen mislukken of een time-out geven.
Testomgeving op aanvraag
Microcash kan voor een ontwikkelproject een testomgeving beschikbaar stellen. Deze draait niet standaard. Vraag de omgeving vóór de start van de ontwikkeling aan en stem toegang, testgegevens en beschikbaarheid af met Microcash, zodat tests geen livevoorraad of livefacturen wijzigen.
Test in ieder geval een gewone bestelling, een retour, een dubbele referentie, een time-out met herhaalpoging en de verwerking van kortingen. Spreek de verwerking van verzendkosten en gifts vooraf af.
2. Artikelstamdata
Microcash plaatst de artikelstamdata op een FTP-locatie. Het bestand bevat de volledige artikelset en wordt dagelijks overschreven. Gebruik dit totaalbestand om de artikelgegevens in de webshop bij te werken.
Voor actuele gegevens tussendoor gebruik je /api/webshop/product. Voor actuele voorraad gebruik je /api/webshop/stock. De voorraad in het productveld Stock bevat alleen de winkelvoorraad, zonder het eigen magazijn; voor de volledige voorraad gebruik je de stock-aanvraag.
3. Algemene API-afspraken
Basis-URL: https://app.microcash.nl. Voeg hier het gewenste endpoint aan toe, bijvoorbeeld https://app.microcash.nl/api/auth/login.
- Alle beschreven endpoints gebruiken POST, ook bij het ophalen van gegevens.
- Aanvragen en antwoorden gebruiken JSON. Verstuur de invoer met UTF-8-encoding.
- Gebruik
Content-Type: application/json. - Verstuur barcodes als strings, zodat eventuele voorloopnullen behouden blijven.
- Controleer naast het HTTP-resultaat ook de inhoud van het antwoord, waaronder
errors.
| Endpoint | Functie |
|---|---|
/api/auth/login |
AccessToken en refreshToken ophalen. |
/api/auth/refresh |
Tokens vernieuwen. |
/api/webshop/stock |
Voorraad per barcode opvragen. |
/api/webshop/invoice |
Factuur aanmaken, met voorraadmutatie tenzij dropship: true. |
/api/webshop/product |
Geselecteerde productgegevens opvragen. |
Voor de drie /api/webshop/-endpoints stuur je deze headers mee:
Authorization: Bearer <accessToken>
X-Api-Key: <verstrekte API-Key>
X-Api-Code: <verstrekte API-Code>
Content-Type: application/jsonVoor login en refresh zijn de Bearer-, X-Api-Key- en X-Api-Code-headers niet nodig.
4. Inloggen en tokens vernieuwen
Login — POST /api/auth/login
Log in met het API-account uit de Microcash Online Helpdesk-portal. De API geeft een accessToken en een refreshToken terug.
Aanvraag
{
"email": "api@example.com",
"password": "<wachtwoord van het API-account>"
}| Veld | Type | Verplicht | Toelichting |
|---|---|---|---|
email |
string | Ja | E-mailadres van het API-account. |
password |
string | Ja | Wachtwoord van het API-account. |
Voorbeeldantwoord
{
"tokenType": "Bearer",
"accessToken": "<accessToken>",
"expiresIn": 3600,
"refreshToken": "<refreshToken>"
}| Veld | Type | Toelichting |
|---|---|---|
tokenType |
string | Type token; in dit voorbeeld Bearer. |
accessToken |
string | Token voor de Authorization-header. |
expiresIn |
integer | Geldigheidsduur van het accessToken. De getoonde waarde is een voorbeeld. |
refreshToken |
string | Token om nieuwe tokens op te vragen. |
Je hoeft niet voor iedere aanvraag opnieuw in te loggen. Hergebruik het accessToken zolang dit geldig is. Vernieuw het daarna met de refresh-aanvraag. Als ook het refreshToken niet meer geldig is, log je opnieuw in.
Refresh — POST /api/auth/refresh
Aanvraag
{
"refreshToken": "<refreshToken uit login of de laatste refresh>"
}refreshToken is verplicht en heeft het type string.
Antwoord
Het antwoord heeft dezelfde velden als het loginantwoord: tokenType, accessToken, expiresIn en refreshToken. Bewaar na een geslaagde refresh zowel het nieuwe accessToken als het nieuwe refreshToken.
5. Voorraad opvragen
POST /api/webshop/stock
Vraag de voorraad op van één of meer producten aan de hand van hun barcode. Deze aanvraag leest voorraad uit Microcash en wijzigt niets in Microcash.
Aanvraag
{
"barcodes": [
"1234567891234",
"2345678912345",
"3456789123456"
]
}| Veld | Type | Verplicht | Toelichting |
|---|---|---|---|
barcodes |
array van strings | Ja | Barcodes waarvoor je de voorraad wilt opvragen. |
Voorbeeldantwoord
{
"products": [
{
"barcode": "1234567891234",
"stock": 6
},
{
"barcode": "2345678912345",
"stock": 27
}
],
"messages": [],
"errors": [
"Barcode niet gevonden: '3456789123456'"
]
}| Veld | Type | Toelichting |
|---|---|---|
products |
array van productobjecten | Producten waarvoor voorraad is opgehaald. |
products[].barcode |
string | Barcode van het product. |
products[].stock |
integer | Voorraad van het product. |
messages |
array van strings | Aanvullende meldingen; momenteel niet in gebruik. |
errors |
array van strings | Foutmeldingen, bijvoorbeeld voor een onbekende barcode. |
Een antwoord kan tegelijk gevonden producten en fouten voor andere barcodes bevatten. Verwerk de teruggegeven voorraad per barcode en registreer de fouten apart. Een ontbrekend product of een mislukte aanvraag betekent niet dat de voorraad nul is.
Batchgrootte en volgorde
Er is geen vaste batchlimiet opgegeven. Ons praktijkadvies is ongeveer 100 artikelen per aanvraag. Dit is een aanbevolen batchgrootte, geen vast maximum.
De API verwerkt aanvragen synchroon, één aanvraag per keer. Verstuur batches daarom na elkaar en wacht op het antwoord voordat je de volgende batch verstuurt.
Voorraad synchroon houden
Er is momenteel geen webhook voor voorraadwijzigingen en geen afzonderlijk endpoint om de voorraad rechtstreeks in Microcash aan te passen. Voorraadmutaties via deze webshop-API verlopen via /api/webshop/invoice.
Laat de koppeling de voorraad periodiek opvragen en de webshop daarmee bijwerken. Stem het interval af op het aantal artikelen en de gewenste actualiteit. Onderzoek bij verschillen eerst de oorzaak, bijvoorbeeld een nog niet verwerkte webshoporder. Een rechtstreekse voorraadcorrectie in Microcash via /stock is niet mogelijk.
6. Een webshopbestelling als factuur aanmaken
POST /api/webshop/invoice
Met deze aanvraag maak je in McWin een factuur aan voor een webshopbestelling. De aanvraag bevat klantgegevens, bestelregels en een unieke webshopreferentie.
Aanvraag
{
"customer": {
"name": "Tinus Test",
"email": "tinus@example.com",
"address": {
"street": "Voorbeeldstraat",
"houseNumber": "1",
"houseNumberAddition": "a",
"zipCode": "1234AB",
"city": "Testdorp"
}
},
"lines": [
{
"barcode": "8720181022548",
"price": 2.49,
"quantity": 1
},
{
"barcode": "3663555004373",
"price": 2.49,
"quantity": 1
}
],
"reference": "123477",
"webshop": "Web",
"paid": true,
"note": "Extra klantbestelling",
"dropship": false
}| Veld | Type | Verplicht | Toelichting |
|---|---|---|---|
customer |
object | Ja | Klantgegevens. |
customer.name |
string | Ja | Naam van de klant. |
customer.email |
string | Ja | E-mailadres van de klant. |
customer.address |
object | Nee | Adresgegevens. |
customer.address.street |
string | Nee | Straatnaam. |
customer.address.houseNumber |
string | Nee | Huisnummer. |
customer.address.houseNumberAddition |
string | Nee | Huisnummertoevoeging. |
customer.address.zipCode |
string | Nee | Postcode. |
customer.address.city |
string | Nee | Woonplaats. |
lines |
array van bestelregelobjecten | Ja | Bestelregels van de factuur. |
lines[].barcode |
string | Ja | Productbarcode. |
lines[].price |
double | Ja | Daadwerkelijke verkoopprijs per stuk, inclusief btw en na eventuele productkorting. |
lines[].quantity |
integer | Ja | Aantal stuks. Negatieve aantallen zijn toegestaan voor retouren of correcties. |
reference |
string | Ja | Unieke referentie uit de webshop, bijvoorbeeld het ordernummer. Een bestaande referentie wordt geweigerd. |
webshop |
string | Nee | Webshopreferentie die in McWin bekend moet zijn. Standaard leeg. |
paid |
boolean | Nee | Geeft aan of de bestelling al betaald is. Standaard false. |
note |
string | Nee | Aanvullende notitie. |
dropship |
boolean | Nee | Bij true wordt de voorraad niet aangepast. Stuur expliciet true of false mee. |
Gebruik voor price een JSON-getal met een decimale punt, bijvoorbeeld 2.49. Stuur de werkelijk berekende verkoopprijs mee; de webshop verwerkt eventuele kortingen vóór het aanleveren.
Voorbeeldantwoord
{
"reference": "123477",
"invoiceNumber": "11W",
"messages": [],
"errors": []
}| Veld | Type | Toelichting |
|---|---|---|
reference |
string | De aangeleverde webshopreferentie. |
invoiceNumber |
string | Het factuurnummer dat McWin heeft aangemaakt. |
messages |
array van strings | Aanvullende meldingen; momenteel niet in gebruik. |
errors |
array van strings | Foutmeldingen bij de aanlevering. |
Controleer het antwoord en sla bij bevestigde verwerking zowel reference als invoiceNumber op bij de webshoporder.
Unieke referentie en dubbele aanlevering
reference is de unieke referentie uit de webshop. Dit is niet het McWin-factuurnummer: dat geeft Microcash terug in invoiceNumber. Als een reference al bestaat, wordt een nieuwe aanlevering met die referentie geweigerd.
- Gebruik bij iedere herhaalpoging voor dezelfde factuur dezelfde
reference. - Maak geen nieuwe referentie aan om een duplicaatmelding te omzeilen. Daarmee kun je een extra factuur en een extra voorraadmutatie veroorzaken.
- Een afzonderlijke retour of correctie heeft een eigen unieke referentie nodig, bijvoorbeeld
123477-RET1. Dit is een voorbeeld van een eigen nummering, geen verplicht API-formaat. - Vermeld bij een retour of correctie de oorspronkelijke orderreferentie in
note, zodat de relatie herkenbaar blijft.
Retouren, creditregels en annuleringen
Een factuur kan negatieve aantallen bevatten. Gebruik een negatieve quantity voor producten die je wilt terugboeken. Dit kan worden gebruikt voor retouren of het terugboeken van een eerder verwerkte bestelling.
| Aanlevering | dropship |
Voorraadeffect |
|---|---|---|
quantity: 1 |
false |
De voorraad neemt met 1 af. |
quantity: -1 |
false |
De voorraad neemt met 1 toe. |
Positieve of negatieve quantity
|
true |
De voorraad verandert niet. |
dropship staat op factuurniveau en geldt voor de hele aanvraag. Bij true wordt dus ook bij een negatief aantal geen voorraad bijgeboekt.
Controleer bij een annulering eerst of de oorspronkelijke bestelling in McWin is verwerkt. Boek geen voorraad terug voor een bestelling die daar nooit is afgeboekt. Een nieuwe correctieaanlevering moet je niet behandelen als het automatisch wijzigen of verwijderen van de oorspronkelijke factuur. De terugbetaling aan de consument regel je afzonderlijk in de webshop of bij de betaalprovider.
Productkortingen, verzendkosten en gifts
| Onderwerp | Verwerking |
|---|---|
| Productkorting | Bereken de korting in de webshop en lever de uiteindelijke verkoopprijs per stuk aan in lines[].price, inclusief btw. Microcash neemt deze prijs over. |
| Orderkorting | Er is geen afzonderlijk veld voor een korting op het ordertotaal. Stem de verwerking over de productregels en eventuele afrondingsverschillen vooraf af. |
| Verzendkosten | Er is geen afzonderlijk veld of standaardafhandeling voor verzendkosten beschreven. Stem vóór implementatie met Microcash af hoe deze moeten worden vastgelegd. |
| Gifts of gratis producten | Er is geen afzonderlijk giftveld of uitgewerkte standaardafhandeling. Stem vooraf af welk type gift bedoeld wordt, welke prijs moet worden aangeleverd en welk voorraadeffect gewenst is. |
Iedere bestelregel heeft een barcode nodig. Ga daarom niet zonder afstemming uit van ondersteuning voor vrije tekstregels, een zelfbedacht verzendartikel of een giftregel met price: 0. Bevestig en test de gekozen verwerking in de testomgeving.
7. Fouten, time-outs en opnieuw aanbieden
Bij een onvolledige aanlevering geeft de API een foutmelding. De koppeling blijft zelf verantwoordelijk voor het volledig aanleveren van de webshopbestelling: controleer vóór verzending of alle bedoelde regels, aantallen en prijzen zijn opgenomen. Een API-aanvraag met geldige invoer vertelt Microcash niet of de webshop een regel heeft weggelaten.
| Situatie | Aanbevolen afhandeling in de koppeling |
|---|---|
| Ontbrekende of onjuiste invoer | Lees de foutmelding, corrigeer de gegevens en bied de aanvraag daarna opnieuw aan. Herhaal niet onbeperkt dezelfde ongeldige invoer. |
| Verlopen toegangstoken | Vernieuw de tokens via refresh. Lukt dat niet doordat het refreshToken ongeldig is, log dan opnieuw in. |
| Tijdelijke onbereikbaarheid of time-out | Herhaal de aanvraag met een beperkt aantal pogingen en oplopende wachttijden. Gebruik bij factuuraanlevering steeds dezelfde inhoud en dezelfde reference. |
| Bestaande reference na een herhaalpoging | Controleer in McWin of de bedoelde factuur met de juiste inhoud is verwerkt. Markeer de order niet uitsluitend op basis van een duplicaatmelding als gesynchroniseerd. |
| Herhaalpogingen blijven mislukken of verwerking blijft onzeker | Zet de order in een overzicht met onverwerkte of te controleren orders en stuur een melding naar de afgesproken beheerder. |
Een time-out bij factuuraanlevering betekent niet automatisch dat de factuur niet is verwerkt. De factuur kan al zijn aangemaakt terwijl het antwoord de webshop niet heeft bereikt. Gebruik daarom nooit een nieuwe referentie voor een herhaalpoging.
De API biedt in deze documentatie geen aparte aanvraag om de verwerkingsstatus van een factuur op te zoeken. Ook is geen garantie beschreven dat bij iedere verwerkingsfout alle wijzigingen worden teruggedraaid. Controleer bij een onzekere uitkomst de bestaande verwerking in McWin voordat je een afwijkende of aanvullende factuur aanlevert.
Aanbevolen werkwijze voor factuuraanlevering vanuit de webshopkoppeling:
- Bewaar de aangeleverde bestelling en referentie, het tijdstip, de pogingen en het ontvangen antwoord.
- Probeer bij een tijdelijke storing eerst enkele keren opnieuw met korte wachttijden en vergroot daarna de wachttijd. Wacht op de uitkomst voordat je dezelfde aanvraag nogmaals verstuurt.
- Spreek vooraf af na hoeveel pogingen of na welke periode de koppeling stopt en wie een melding ontvangt.
- Houd orders zonder bevestigde verwerking zichtbaar als onverwerkt of te controleren. Leg na controle ook het bijbehorende McWin-factuurnummer vast.
Deze herhaalpogingen, meldingen en het overzicht moeten door de webshopkoppeling worden verzorgd; dit is geen automatische functie van de beschreven API.
8. Actuele productgegevens opvragen
POST /api/webshop/product
Vraag geselecteerde productvelden live op uit McWin, voor één of meer barcodes.
Aanvraag
{
"barcodes": [
"1234567891234"
],
"fields": [
"salesPrice",
"group",
"currentPrice",
"name"
]
}| Veld | Type | Verplicht | Toelichting |
|---|---|---|---|
barcodes |
array van strings | Ja | Productbarcodes waarvoor je informatie wilt ontvangen. |
fields |
array van strings | Ja | Productvelden die je wilt opvragen; zie de tabel hieronder. |
Beschikbare productvelden
| Veld | Betekenis |
|---|---|
Name |
Productomschrijving. |
Number |
PLU / artikelnummer. |
Stock |
Winkelvoorraad zonder eigen magazijn. Gebruik /api/webshop/stock voor de volledige voorraad. |
SalesPrice |
Verkoopprijs inclusief btw. |
TemporaryPrice |
Tijdelijke verkoopprijs inclusief btw. |
TemporarySince |
Startdatum van de tijdelijke verkoopprijs. |
TemporaryUntil |
Einddatum van de tijdelijke verkoopprijs. |
CurrentPrice |
Kassaprijs inclusief btw. |
VATCode |
Btw-code: N = nul, L = laag, M = midden, H = hoog. M wordt niet gebruikt in Nederland. |
Group |
Groepcode. |
Brand |
Merkcode. |
Category |
Categorie. |
Memo1, Memo2, Memo3, Memo4
|
Vrije invoervelden. |
Webshop |
Voor welke webshop het product beschikbaar is; NEE betekent niet beschikbaar voor webshops. |
StockMinimum |
Minimale winkelvoorraad. |
StockMaximum |
Maximale winkelvoorraad. |
ProductRange |
Assortiment. |
Voorbeeldantwoord
{
"products": [
{
"barcode": "1234567891234",
"fields": [
{
"field": "SalesPrice",
"value": "0,85"
},
{
"field": "Group",
"value": "404"
},
{
"field": "CurrentPrice",
"value": "0,85"
},
{
"field": "Name",
"value": "Testproduct"
}
]
}
],
"messages": [],
"errors": []
}| Veld | Type | Toelichting |
|---|---|---|
products |
array van productobjecten | Producten waarvoor informatie is opgehaald. |
products[].barcode |
string | Barcode van het product. |
products[].fields |
array van veldobjecten | De opgevraagde velden en waarden. |
products[].fields[].field |
string | Naam van het teruggegeven productveld. |
products[].fields[].value |
string | Veldwaarde, of een speciale waarde zoals hieronder beschreven. |
messages |
array van strings | Aanvullende meldingen. |
errors |
array van strings | Foutmeldingen bij de aanvraag. |
value is een string, ook bij prijzen en andere numerieke gegevens. Het voorbeeld geeft een prijs terug als "0,85". Houd hiermee rekening bij het omzetten naar getallen. Dit verschilt van lines[].price bij een factuur: daar stuur je een JSON-getal met een decimale punt.
-
<UNKNOWN>: het opgegeven productveld is niet bekend. -
<NOTINUSE>: het productveld is niet in gebruik.