The same analysis as an on-prem container in your network
The API is the same analysis engine as in the desktop program, packaged as a container image that you run on-prem, meaning on a server of your own or in your cluster. Your systems send the card files to the container over HTTP and get the analysis back as JSON. The container keeps the card files in memory only. It does not save them to disk and writes them to no log file. It sends neither the card files nor the results to us. So that we can count how many drivers you analyse with your licence, it connects to our licence service at license.scernetta.com after it starts, about every 6 hours and when a new driver appears. The licence service then receives the text of your licence file with your company name, the version number of the container, a few technical check values and, for each new driver, a driver code. The container computes the driver code on your server from the driver card and your secret key.
Who it is for
It is meant for fleets with their own TMS or ERP that want to process the analysis there. Telematics providers that collect card data anyway can have it checked directly, and service providers that analyse driver cards for many customers save themselves the detour through a desktop program.
How it works
You receive a licence file from us. Before the first start you create a secret key once, with a command from the container image; the container computes the driver codes from it. Use this key on all installations and keep a copy. The container runs on a server in your network and needs a folder of its own there, where it keeps which drivers already have a driver seat. The server must be able to reach license.scernetta.com, directly or through your HTTP proxy. Your systems sign in with an API key and hand over the .ddd files over HTTP, one at a time or bundled per driver, and the container merges them exactly the way the desktop program does. Back comes a JSON with the shifts, the violations of the chosen view, the forecasts and the periods that are not assessable, which you can process straight away.
For a whole fleet at once there is a batch endpoint. You upload all files in one request, the container assigns them to their drivers itself and works through them in the background. For every new driver in the request the container takes a driver seat as soon as the request is submitted. If the free driver seats are not enough for all new drivers, it refuses the whole request and takes no seat. Progress and the per-driver results are fetched through a job id.
Same engine
The desktop program and the API run the same code. For the same file and the same view, the API delivers the same results as the program, as data.
Two views
Every answer carries one of the two violation lists. The default is the strict view, which derives each finding from the regulation text and cites the article. Under EU law you can ask for the reference view instead, which is calibrated against the output of established software. Under the Swiss rules ARV 1 and ARV 2 there is only the strict view. A separate endpoint returns the catalogue of the rules with their citations.
Reports
The report from the desktop program is available through the API as well, as HTML or as CSV tables in a zip. It comes with a source manifest that states which uploaded file backs which day.
Authenticity
The signatures and certificates of a driver card or a vehicle-unit download can be verified through the API. The answer says what was verified. This version does not yet check the signatures of the first card generation, and that is no sign of tampering.
Vehicle unit
The download file of the vehicle can be read as well. You see which cards were inserted in a period and which drivers drove with them.
Generations
Driver cards of generation 1 and of generation 2 including version 2 are read. Vehicle unit files are read in the generation 2 formats only.
OpenAPI
The interface is described as an OpenAPI 3.1 specification that the container serves itself. The documentation at docs.scernetta.com is generated from it.
How drivers are counted
Each driver card you analyse during the term of your licence counts once as a driver, however often you analyse it. A driver who gets a renewed or replacement card stays the same driver. A driver who gets a card from another country counts as a new driver. A driver keeps their driver seat until the term ends, even after they have left your company. The count covers all your installations together, a test installation included. The sample card from our website, the authenticity check and vehicle unit files take no driver seat.
Licensing
The API is licensed by the number of drivers and billed annually. The container checks by its digital signature whether the licence file is genuine, and needs no connection to us for that. The first time a driver is analysed in a term, the container asks our licence service for a driver seat for that driver. When a paid licence expires, the container keeps working for 14 days, so the analysis does not stop when a renewal comes a few days late. We quote the price on request, because it depends on the size of the fleet.
Without a connection to the licence service
The container keeps analysing drivers who already have a driver seat without a connection to our licence service, for 30 days from the last connection, 14 days with a trial licence. For new drivers a paid licence has a reserve in case our licence service cannot be reached for more than a minute. The reserve is a tenth of the driver seats, but at least 2 seats per term, so 3 with 30 seats. For this the container needs its folder on the server. It reports these drivers as soon as the licence service can be reached again. A trial licence has no reserve.
What leaves your server
The card files are processed on-prem, inside your network, and are never sent to us. The container computes the driver code on your server from the driver card and your secret key, which we never receive. We cannot tell from the code who the driver is. Your key can link the code back to a driver, though, so the driver code is personal data under the GDPR. You can fetch and read the last 20 messages the container has sent to our licence service since it started, as they were before they were encrypted.
The documentation of the interface lives at docs.scernetta.com and is generated from the OpenAPI file. It opens with a guide to getting started, licensing and error handling and describes every endpoint with its parameters.Go to the documentation
If you want to use the API, tell us which systems you would like to connect and how many drivers or vehicles are involved. We will get back to you with access.