Documentation

Definitions

Supplier

A supplier is a difficult definition, because in the context of the platform there are POS vendors, or suppliers of bicycles and bicycle parts. However, we speak of suppliers as being suppliers of data to the platform. Practically these are producers or wholesalers, but they can also be other types of parties.

Customers

Customers are parties who want to retract product information from the platform. In general these will be retailers, but other parties can be connected (e.g. POS vendors or Retail Service Organizations).

Parties

In the DST standard, there is a list of parties “party” as a separate code list. The platform parties are those parties that connect to the platform to deliver data, or to retract data.

Base URL’s

Acceptance environment (copy prod)

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

Production environment:

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

These are the base URLs. The exact web services are described later on in relation to this base URL, for example: the code lists web service on production, can be found here.

For development purposes/ initial set‐up / configuration, you should use the acceptance URL. This is a test environment, which may also include “test data”. The production URL is obviously the desired URL for production purposes.

Security

For all the methods in the API that can be used by applications, two values must always be given.
These values are:

  • usr = the string that indicates who is requesting access.
  • pwd = the string that requires a password.

In this usr refers to the username of a user. And pwd is a password.

Interfaces

FTP in

A way to provide product information to the platform is via the FTP‐in method. This works similar to how suppliers already offer data to Biretco and Bike Totaal.

  • The supplier has its own FTP environment, where they place a complete product file.
  • The format of this file is CSV.
  • They provide access to the platform.
  • The platform downloads the product file according to an agreed frequency (e.g. daily, weekly) or occasionally on request.
  • The downloaded file will be processed by an import job.
  • An import report will be sent to a specified email‐address.

The FTP‐in (CSV) for v2.X supports a reduced version of the standard. Main difference is that you can link only one accu per electric bicycle, instead of multiple (the API supports the full model/ business logic).

Web services

The default web service is a REST web service that accepts its arguments via http methods. The return format of the web service is JSON. We choose REST instead of SOAP, because;

  1. REST web service is much easier to deploy through simple HTTP GET on the calling side.
  2. The JSON response format uses much less Kb’s on data, because it is not CSV and therefore there is less overhead.

API methods

The base URLs for the web service are as follows:
Production: api‐v2.platformdst.nl/swagger‐ui.html
Acceptance: api‐v2.acceptance.platformdst.ritense.com/swagger‐ui.html

Whitin SWAGGER all the calls are visible even when a user does not have the proper rights to use them. When you as a user do not have the rights the test call functionallity will not work and will return a restriction error.

When navigating the the SWAGGER environment for the first time it can occure that nothing is made visiable. We advice to refresh the page several times until you see a screen that looks a bit like this;

DST Swagger Interface

Web interface

With http://www.platformdst.nl the platform also has a web interface which can be operated manually in contrast to the automated web service interface.