Documentatie

Definities

Leverancier

In de context van het platform is een leveranciers een leveranciers van fietsen en fietsonderdelen die artikeldata aanlevert bij het platform. Meestal zijn dit producenten of groothandelaren, maar het kunnen ook andere soorten partijen zijn.

Afnemers

Afnemers zijn partijen die productinformatie van het platform willen ontvangen. In het algemeen zullen dit detailhandelaars zijn, maar er kunnen ook andere partijen zijn die data willen ontvangen (zoals systeem leveranciers (POS / e-commerce), Retail Service-Organisaties en Platformen).

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 artikelgegevens aan te leveren.


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 webservices zijn te vinden binnen onze Swagger omgeving waarvan de url onderaan deze pagina te vinden is.

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.

  • 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.