dgeAPI: Technische documentatie

Met de dgeAPI is het mogelijk om externe toepassingen (zoals een app of een webshop) toegang te geven tot de data in dgeDetailhandel en dgeGroothandel.

Over het algemeen wordt een externe toepassing als volgt gekoppeld met dgeDetailhandel of dgeGroothandel.

Bulkexport

Periodiek, bijvoorbeeld iedere nacht, wordt er een bundelbestand (ZIP) klaargezet met daarin de informatie, prijzen en voorraad van alle producten die benoemd zijn tot het eigen assortiment.

Het bundelbestand (ZIP) bevat het bestand "__index__.json". Aan de hand van dit bestand is op basis van een timestamp te bepalen welke artikelen zijn gewijzigd sinds de laatste import:
 

In dit indexbestand verwijzen de attributen "file" en "idx" naar het betreffende databestand en de positie in het databestand.

Meer informatie over de opmaak van databestanden in het bundelbestand (ZIP) is te vinden in de bijlage van de pagina Export Eigen assortiment in PRODUCT DR3-002 formaat

Het bundelbestand wordt gehost op een webserver en kan door middel van een (beveiligde) API call worden opgehaald.

Voor de bulkexport is module 311 vereist.

Categorieën

De bulkexport bevat geen categorie-indeling. Voor het indelen van de producten in categorieën zijn drie oplossingen mogelijk:

1. De webshop biedt de mogelijkheid om producten in categorieën in te delen.
2. De producten worden met behulp van de Product Data Editor in categorieën ingedeeld. De Product Data Editor is een online tool waarmee je de artikelen in je eigen assortiment kan indelen in categorieën en collecties. Een collectie van producten kan worden voorzien van filterattributen.
   Voor de Product Data Editor is module 1003 vereist.
   
   
   
   
   Een categorie- en collectiestructuur kan door de ondernemer gepubliceerd worden. Het resultaat is een URL aan de hand waarvan de externe toepassing de categorie- en collectiestructuur kan ophalen. Zie voor een voorbeeld het bestand example.cls.dr3.zip dat als bijlage is toegevoegd aan deze pagina. Het bestand example_collection.md bevat een korte uitleg over de opbouw van een collectie.
3. De webshop maakt gebruik van EZ-Base om de producten in categorieën in te delen.

   Bij EZ-Base dient hiervoor een abonnement afgesloten te worden. Om te gebruik te kunnen maken van EZ-Base is module 310 (koppeling EZ-Base) vereist.

API

Voor het gebruik van de API is module 1000 vereist. 

De externe toepassing kan de API gebruiken om real-time informatie op te vragen zoals de actuele voorraad van een product, de korting en nettoprijs van een product voor een bepaalde klant, verkoopbonnen, facturen, enz.

Techniek

Voordat er gebruik gemaakt gaat worden van de API is het goed om enig inzicht te hebben van hoe API calls afgehandeld worden.

Api-service

Als een externe toepassing een API call uitvoert dan wordt de API call eerst behandeld door de ‘api-service’.

De ‘api-service’ wordt gehost in een datacenter. De ‘api-service’ controleert de geldigheid van binnenkomend verzoek en valideert de inhoud van de aanvraag. Als het verzoek geldig is, wordt het verzoek (via een geëncrypte beveiligde verbinding) doorgestuurd naar de socketserver.

Socketserver

Lokaal in het netwerk van de klant, op de fileserver van de klant, is een socketserver actief. De socketserver controleert de geldigheid van het verzoek en handelt het verzoek af door de gewenste data bij de databaseserver op te vragen.

De socketserver stuurt vervolgens het antwoord terug naar de 'api-service' die het weer als antwoord doorstuurt naar de aanvrager.

Beschikbaarheid

De beschikbaarheid en prestaties van het verwerken van een dgeAPI-verzoek zijn dus afhankelijk van de beschikbaarheid en prestaties van de lokale server en internetverbinding van de klant.

De externe toepassing moet daarom zo opgezet worden dat het aantal API calls tot een minimum wordt beperkt. Dit om de server van de klant zo min mogelijk te belasten.  Wij adviseren dan ook om zo veel mogelijk informatie op te halen uit het exportbestand dat 's nachts wordt klaargezet.

Documentatie

Een overzicht van alle API calls is te raadplegen op: https://docs.dgebv.io/dgeapi/dge.html (deze pagina vereist een gebruikersnaam en wachtwoord; deze kunnen worden opgevraagd bij dge)

Iedere API call bevat een JSON schema. In een JSON schema wordt de vereiste structuur van een JSON bericht beschreven. Met behulp van https://navneethg.github.io/jsonschemaviewer/ is het mogelijk om een JSON schema grafisch weer te geven. Deze weergave geeft een sneller inzicht in welke objecten en attributen verplicht zijn.

In de documentatie wordt per API call aangegeven in welke versie van dgeDetailhandel of dgeGroothandel de API call beschikbaar is. Als bij een API call "NIY" (Not Yet Implemented) staat dan is de API call nog niet beschikbaar. De betreffende API call zal dan in de toekomst aan de API worden toegevoegd.

Kosten

De kosten voor het gebruik van de API zijn afhankelijk van de aard van de toepassing, de API calls waartoe toegang gewenst is en het aantal te verwachten dagelijkse API verzoeken. Neem voor meer informatie contact op met dge.

Voorbeeld toepassing: externe webshop

Een externe webshop kan als volgt met de API worden gekoppeld:

• Iedere nacht wordt er een bulkbestand (in JSON formaat) klaargezet met daarin product- en bruto prijsinformatie van de artikelen in het eigen assortiment. Zie voor meer informatieExport Eigen assortiment in PRODUCT DR3-002 formaat
  Deze bulkdata kan gebruikt worden om 's nachts sneller de product- en bruto prijsinformatie op de webshop bij te werken. 
• De API wordt overdag gebruikt om actuele real-time gegevens op te vragen. Veel gebruikte API calls zijn:
  • GET /dge/v1/apps/{app_id}/contacts
    In dgeDetailhandel of dgeGroothandel kan bij een contactpersoon worden aangegeven dat deze van een externe toepassing, in dit geval de webshop, gebruik mag gaan maken.  Met behulp van de API call kunnen de contactpersonen worden opgevraagd die toegang hebben gekregen tot de webshop. De webshop kan vervolgens logingegevens verstrekken aan de contactpersoon.
  • GET /dge/v1/products/{product_id}/pricesof GET /dge/v1/products/prices
    Met deze call kan de nettoprijs/korting van een klant voor één (of meerdere) producten worden opgevraagd.
  • GET /dge/v1/products/{product_id}/stockof GET /dge/v1/products/stock
    Met deze call kan de voorraad van een product worden opgevraagd.
  • POST /dge/v1/webshoporders-in
    Met deze call kan een order worden aangemaakt in dgeDetailhandel of dgeGroothandel.

Standaard krijgt een webshop toegang tot de volgende API calls:

{"uri":"GET /dge/v1/apps/{app_id}/contacts","filter":[{"member":"app_id","value":["0"]}]},
{"uri":"GET /dge/v1/invoices","filter":[]},
{"uri":"GET /dge/v1/invoices/{invoice_id}/pdf","filter":[]},
{"uri":"GET /dge/v1/offers","filter":[{"member":"status","value":["offered","accepted","done","backorder"]}]},
{"uri":"GET /dge/v1/offers/{offer_id}/pdf","filter":[{"member":"status","value":["offered","accepted","done","backorder"]}]},
{"uri":"GET /dge/v1/parties/{party_id}","filter":[]},
{"uri":"GET /dge/v1/parties/{party_id}/contacts","filter":[]},
{"uri":"GET /dge/v1/parties/{party_id}/contacts/{contact_id}","filter":[]},
{"uri":"GET /dge/v1/parties/{party_id}/deliveryaddresses","filter":[]},
{"uri":"GET /dge/v1/parties/{party_id}/deliveryaddresses/{deliveryaddress_id}","filter":[]},
{"uri":"GET /dge/v1/products/{product_id}/prices","filter":[]},
{"uri":"GET /dge/v1/products/prices","filter":[]},
{"uri":"GET /dge/v1/products/{product_id}/stock","filter":[]},
{"uri":"GET /dge/v1/products/stock","filter":[]},
{"uri":"GET /dge/v1/salesorders","filter":[{"member":"status","value":["open"]}]},
{"uri":"GET /dge/v1/salesorders/{salesorder_id}/pdf","filter":[{"member":"status","value":["open"]}]},
{"uri":"POST /dge/v1/webshoporders-in","filter":[]},
{"uri":"GET /dge/v1/webshoporders-in/{webshoporderin_id}/status","filter":[]}