Documentatie

Definities

Leverancier

‘De leverancier’ is een lastige definitie omdat er in de context van het platform twee soorten leveranciers zijn: POS-leveranciers en leveranciers van fietsen en fietsonderdelen. We spreken van een leverancier als leverancier van datagegevens aan het platform. Meestal zijn dit producenten of groothandelaren, maar het kunnen ook andere soorten partijen zijn.

Klanten

Klanten zijn deel van partijen die productinformatie van het platform willen intrekken. In het algemeen zullen dit detailhandelaars zijn, maar er kunnen ook andere partijen worden verbonden (bijvoorbeeld POS-leveranciers of Retail Service-Organisaties).

Partijen

In de DST-standaard is er een lijst met partijen als een afzonderlijke codelijst, deze lijst heet “Partij”. De platform-partijen zijn de partijen die verbinding maken met het platform om gegevens te leveren of om gegevens in te trekken.


Basis URL’s

Acceptatie omgeving (copy prod)

https://admin.acceptance.platformdst.ritense.com
api‐v2.acceptance.platformdst.ritense.com

Productie omgeving

https://admin.platformdst.nl
api‐v2.platformdst.nl

Dit zijn de basis-URL;s. De exacte wegservices worden later beschreven in relatie tot deze basis-URL’s. Bijvoorbeeld: de codelijsten web service bij productie, is hier te vinden.

Voor ontwikkelingsdoeleinden / initiële set-up / configuratie kunt u de acceptatie-URL gebruiken. Dit is een testomgeving, die ook testgegevens bevat. De productie-URL is de ideale URL voor productiedoeleinden.


Veiligheid

Voor alle methodes in de API die door toepassingen kunnen worden gebruikt, moeten altijd twee waarden worden opgegeven.
Deze waarden zijn:

  • usr – geeft aan wie toegang vraagt
  • pwd – wachtwoord is vereiste

usr verwijst naar de gebruikersnaam van een gebruiker en pwd is een wachtwoord.


Interfaces

FTP in

Een manier om productinformatie aan het platform te leveren is via de FTP-in-methode. Dit werkt op dezelfde manier als leveranciers al gegevens aanbieden aan bijvoorbeeld Biretco en Bike Totaal.

  • De leverancier heeft zijn eigen FTP-omgeving, waar ze een compleet productbestand plaatsen;
  • Het formaat van dit bestand is CSV;
  • De leverancier biedt toegang tot het platform;
  • Het platform downloadt het productbestand volgens een afgesproken frequentie (bijvoorbeeld dagelijks, wekelijks) of af en toe op aanvraag;
  • Het gedownloade bestand wordt verwerkt door een importjob;
  • Er wordt een importrapport verzonden naar een opgegeven e-mailadres.

De FTP-in (CSV) voor v2.X ondersteunt een beperkte versie van de standaard. Belangrijkste verschil is dat je slechts één accu per elektrische fiets kunt koppelen, in plaats van meerdere (de API ondersteunt de volledige model / bedrijfslogica).

Webservices

De standaardwebservice is een REST-webservice die zijn argumenten accepteert via http-methoden. Het retourformaat van de webservice is JSON. We kiezen REST in plaats van SOAP, omdat;
REST-webservice is veel eenvoudiger in te zetten via eenvoudige HTTP GET aan de desbetreffende kant.
Het JSON-antwoordformaat gebruikt veel minder Kb’s voor gegevens, omdat het geen CSV is en er daarom minder overhead is.

API-methoden

De basis-URL’s voor de web-service zijn:
Productie – api‐v2.platformdst.nl/swagger‐ui.html
Acceptatie – api‐v2.acceptance.platformdst.ritense.com/swagger‐ui.html

Bij SWAGGER zijn alle oproepen zichtbaar, zelf als een gebruiker niet over de juiste rechten beschikt om deze te gebruiken. Wanneer u als gebruiker niet over de rechten beschikt, werkt de testoproep-functionaliteit niet en ontvangt u een beperkingsfout.

Als u voor het eerst navigeert in de SWAGGER omgeving kan het voorkomen dat niets zichtbaar wordt gemaakt. We raden u aan de pagina meerdere keren te verversen totdat u een scherm ziet dat er ongeveer zo uitziet:

Web interface

Met http://www.platformdst.nl beschikt het platform ook over een web interface die handmatig kan worden bediende in tegenstelling tot de geautomatiseerde webservice-interface.