Mobility as a Service (Maas) | Connecting to the Dutch MaaS Pilot Router
The ACCEPT Institute hosts this page which holds all the information available for a MaaS Service Provider (MSP) to make use of the MaaS-NL-Router (Dutch MaaS Pilot Router) for sharing MaaS-data with the MaaS Learning Environment and for the issuance of the MaaS-ID.
You will find links to the current documentation, URLs of the used API Endpoints, a short step-by-step instruction and some FAQs.
Please note that most of the information linked here is hosted on a secure page for which you need the security certificate provided by ACCEPT Institute.
For access to the secure page, questions and/or comments regarding the information provided, please contact us at the following e-mail address: maasadministrator@acceptinstitute.eu
High Level Architecture
The high-level architecture is presented in the picture below:
Documentation
A full description how to connect to the MaaS-NL-Router, to onboard your End Users (travelers), request the MaaS-ID and send valid transactions to the MaaS-NL-Router is given in these documents.
A full API description can be found on our swagger page.
The latest version of the MaaS Base Tables can be found here.
Test set
The MaaS-NL-Router has been tested with a custom built application simulating semi-realistic user trips made by thousands of users. On this Github page the main algorithms used are presented, as well as an example of a logfile generated by the creation of a batch of these trips.
API Endpoints
The 4 endpoints of the MaaS-NL-Router used in this pilot are presented below. Please refer to the detailed documentation on how to use these endpoints.
For onboarding of customers:
1. For the creation of account ID’s for customers: https://maas-nl-hub.westeurope.cloudapp.azure.com/Sensor/v3/Account/Create
2. To request a list of available services a customer can be subscribed to: https://maas-nl-hub.westeurope.cloudapp.azure.com/Sensor/v3/Sensors/Services
3. To subscribe a customer to a service: https://maas-nl-hub.westeurope.cloudapp.azure.com/Sensor/v3/Account/SubscriptionChange
For transaction messages:
4. The main endpoint, to send transaction messages to: https://maas-nl-hub.westeurope.cloudapp.azure.com/Sensor/v3/Trigger
Step-by-step instructions
If helpful, please follow these step-by-step instructions to successfully connect and make use of the MaaS-NL-Router:
WHAT | FURTHER INFORMATION |
Send in MSP Application form | Connecting a MSP to the MaaS-NL-Router – Appendix A |
Create a certificateset and send the public key to the MaaS admin | Connecting a MSP to the MaaS-NL-Router – Chapter 3 |
Register a (test-)End User | Connecting a MSP to the MaaS-NL-Router – Chapter 4.1 |
Check what service the End User needs to subscribe to (note: in the pilot this will always have ServiceId 21) | Connecting a MSP to the MaaS-NL-Router – Chapter 4.2 |
Subscribe the End User to the service | Connecting a MSP to the MaaS-NL-Router – Chapter 4.2 |
Send transaction(s) to the MaaS-NL-Router | Connecting a MSP to the MaaS-NL-Router – Chapter 5 Swagger page |
FAQ
The API responds with a HTTP 400 “CertificateThumbprint is not registered to sensor” error
Please make sure the HTTP header of your message contains a CertificateThumbprint element with the exact thumbprint value from the key registered with the MaaS admin. If this is the case, please contact the admin to make sure the correct thumbprint is registered.
The API responds with a HTTP 401 “Invalid signature value”
There are multiple reasons why this error can occur. Please make sure if any of the following applies to your case:
o The Client-Signature is the hash generated from signing the following string with your certificate:
“POST|{APIURL in UPPERCASE(!)}|{sensorId in lowercase without dashes(!)}|{thumbprint in UPPERCASE(!)}|{messagebody}”. Also make sure the messagebody used for the hash generation is exactly the same as the message sent to the API.
o The signature generated must be SHA256withRSA hashed.
o The message sent to the API must be UTF-8 encoded. If not the case, this may cause certain characters from the messagebody received (and parsed to check the validity of the sent signature) to differ, causing a mismatch in the signature.