← Terug naar kennisbank
Kennisbankartikel

Webshopkoppeling documentatie

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/json

Voor 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:

  1. Bewaar de aangeleverde bestelling en referentie, het tijdstip, de pogingen en het ontvangen antwoord.
  2. 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.
  3. Spreek vooraf af na hoeveel pogingen of na welke periode de koppeling stopt en wie een melding ontvangt.
  4. 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.

Heeft dit artikel je geholpen?

Aantal gebruikers dat dit nuttig vond: 0 van 0
Klopt dit artikel niet? Geef het door

Kom je er niet uit?

Maak een melding aan. Vermeld wat je al hebt geprobeerd en voeg eventueel een foto of foutmelding toe.

Vraag of probleem melden Terug naar kennisbank