Regeling van de Staatssecretaris van Infrastructuur en Waterstaat, van 3 juni 2025, nr. IENW/BSK-2025/130201, houdende regels met betrekking tot de centrale database taxivervoer (Regeling centrale database taxivervoer) [KetenID WGK026754]
Regeling centrale database taxivervoer
De Staatssecretaris van Infrastructuur en Waterstaat,
centrale applicatie: applicatie die taxivervoergegevens ontvangt van een of meerdere registratiemiddelen en deze aanlevert aan de CDT via de CDT meldingen API;
CDT: centrale database taxivervoer;
CDT Meldingen API: voorziening voor het uitwisselen van taxivervoergegevens tussen een centrale applicatie en de CDT;
gebeurtenis: voorval dat plaatsvindt binnen het registratiemiddel, zijnde een melding, fout of storing;
ICT-oplossing: het geheel aan digitale technieken en processen voor het registreren van taxivervoergegevens en het aanleveren van deze gegevens aan de CDT;
pauze: een periode van tenminste 15 achtereenvolgende minuten waarin de bestuurder geen werkzaamheden verricht en vrijelijk over zijn tijd kan beschikken;
twee factor authenticatie: methode waarbij de identiteit van een persoon wordt vastgesteld op basis van twee verschillende factoren.
§
2
Registratie en aanlevering van taxivervoergegevens
Artikel
2
(Registreren en aanleveren van taxivervoergegevens)
1
De centrale applicatie waarvan de vervoerder gebruik maakt, wordt aangesloten op de CDT als het registratiemiddel en de centrale applicatie voldoen aan de in deze regeling opgenomen voorwaarden.
2
Via de CDT Meldingen API meldt de vervoerder van welke ICT-oplossing gebruik wordt gemaakt.
3
De bestuurder maakt gebruik van het registratiemiddel, dat ter beschikking is gesteld door de vervoerder, om taxivervoergegevens te registreren.
4
De taxivervoergegevens worden door het registratiemiddel geregistreerd en via de centrale applicatie realtime aangeleverd aan de CDT Meldingen API, tenzij sprake is van omstandigheden ten gevolge waarvan deze gegevens niet realtime kunnen worden geregistreerd of aangeleverd.
5
De omstandigheden waaronder taxivervoergegevens niet realtime kunnen worden aangeleverd, bedoeld in het vijfde lid, zijn beperkt tot:
a.
het niet beschikbaar zijn van de CDT Meldingen API als gevolg van technische problemen of onderhoud;
b.
een verstoring van de gegevensoverdracht tussen centrale applicatie en CDT Meldingen API.
6
De niet tijdig aangeleverde taxivervoergegevens, bedoeld in het vierde lid, worden onverwijld aangeleverd aan de CDT Meldingen API zodra de omstandigheden, bedoeld in het vijfde lid, zich niet meer voordoen.
7
Het registreren en aanleveren van taxivervoergegevens vindt plaats aan de hand van de beschrijving, bedoeld in de bijlage.
Artikel
3
(Zorgplichten vervoerder)
1
De vervoerder stelt aan de bestuurder een deugdelijk registratiemiddel ter beschikking.
Indien het registratiemiddel ondeugdelijk, defect of verloren gegaan is, zorgt de vervoerder binnen drie werkdagen voor herstel of een vervangend registratiemiddel.
4
De vervoerder draagt er zorg voor dat de gegevens, als bedoeld in artikel 7, zesde lid, onverwijld en waarheidsgetrouw worden aangeleverd aan de CDT Meldingen API.
5
De vervoerder draagt er zorg voor dat de aanlevering aan de CDT Meldingen API zonder foutmeldingen en waarschuwingsberichten verloopt.
6
Als foutmeldingen of waarschuwingsberichten worden ontvangen, verhelpt de vervoerder onverwijld de oorzaken ervan.
Artikel
4
(Validatie van de bestuurder)
1
De vervoerder valideert de gegevens van de bestuurder bij de CDT Meldingen API voordat de bestuurder voor de eerste keer met het registratiemiddel taxivervoer verricht voor de vervoerder.
2
Validatie vindt plaats door het aanleveren van het chauffeursnummer en de rijbewijsgegevens van de bestuurder zoals omschreven in de bijlage.
3
De bestuurder is gevalideerd als:
a.
de rijbewijsgegevens van een geldig rijbewijs zijn;
b.
het chauffeursnummer van een geldige bevoegdheid taxivervoer is; en
c.
het chauffeursnummer en het rijbewijs van dezelfde persoon zijn.
4
Een niet-gevalideerde bestuurder mag geen taxivervoer voor een vervoerder verrichten, tenzij de CDT Meldingen API niet beschikbaar is ten tijde van de validatiepoging.
5
Als sprake is van een situatie als bedoeld in het vierde lid, valideert de vervoerder de gegevens als bedoeld in het tweede lid, onverwijld, zodra de CDT Meldingen API weer beschikbaar is.
6
Als de bestuurder niet in het bezit is van een Nederlands rijbewijs, maar van een niet-Nederlands rijbewijs, valideert de vervoerder het chauffeursnummer van de bestuurder.
7
De bestuurder met een niet-Nederlands rijbewijs is gevalideerd als het chauffeursnummer van een geldige bevoegdheid taxivervoer is.
Artikel
5
(Validatie van de auto waarmee taxivervoer wordt verricht)
1
De vervoerder valideert een auto waarmee taxivervoer wordt verricht voordat deze voor de eerste keer voor de vervoerder met het registratiesysteem van de CDT wordt gebruikt en legt dit vast.
2
Validatie vindt plaats door het elektronisch valideren van het kentekenbewijs.
3
In een niet door de vervoerder gevalideerde auto waarmee taxivervoer wordt verricht, wordt door een bestuurder geen taxivervoer verricht.
Artikel
6
(Aanmelden van de bestuurder)
1
Bij aanvang van de werkzaamheden aan boord van een auto waarmee taxivervoer wordt verricht meldt de bestuurder zich aan op het registratiemiddel.
2
De bestuurder die in het bezit is van een Nederlands rijbewijs meldt zich aan door zijn Nederlands rijbewijs elektronisch te authentiseren op het registratiemiddel.
3
Als het Nederlands rijbewijs defect is, meldt de bestuurder zich gedurende een periode van maximaal tien aaneengesloten dagen aan door middel van twee factor authenticatie.
4
De bestuurder die niet in het bezit is van een Nederlands rijbewijs en wel in het bezit is van een niet-Nederlands rijbewijs meldt zich aan door middel van twee factor authenticatie.
5
Zonder aanmelden is het een bestuurder niet toegestaan om taxivervoer te verrichten.
Artikel
7
(Gebruik van het registratiemiddel door de bestuurder)
1
Indien de bestuurder, voorafgaand aan de melding, bedoeld in artikel 6, eerste lid, andere werkzaamheden heeft verricht na zijn laatste afmelding als bedoeld in het zevende lid van dit artikel, registreert hij de begin- en eindtijden van de andere werkzaamheden bij de melding als bedoeld in artikel 6, eerste lid.
2
De bestuurder meldt een rit aan op het registratiemiddel op het moment dat het vervoeren van personen aanvangt.
3
De bestuurder meldt een rit af op het registratiemiddel op het moment dat het vervoeren van personen is beëindigd.
4
Ingeval het registratiemiddel niet gekoppeld is aan de taxameter, bedoeld in artikel 78 van het Besluit personenvervoer 2000, voert de bestuurder handmatig de door de taxameter aangegeven totaalprijs in. Als voor het vervoer geen taxameter verplicht is en de volledige ritprijs direct na de rit wordt voldaan voert de bestuurder de door de reiziger verschuldigde vergoeding in.
5
Gedurende de periode dat er geen registratiemiddel beschikbaar is, als genoemd in artikel 3, derde lid, registreert de bestuurder zijn taxivervoersgegevens op een andere inzichtelijke en controleerbare wijze.
6
De bestuurder levert de registratie, genoemd in het vijfde lid, uiterlijk de derde werkdag als bedoeld in artikel 3, derde lid, aan bij de vervoerder.
7
Bij beëindiging van de werkzaamheden aan boord van een auto waarmee taxivervoer wordt verricht meldt de bestuurder zich af op het registratiemiddel.
8
De bestuurder meldt op het moment dat deze plaats vinden op het registratiemiddel het begin en einde van pauzes die hij tijdens zijn werkzaamheden aan boord van een auto waarmee taxivervoer wordt verricht geniet.
§
3
Techniek
Artikel
8
(Registratiemiddel)
1
Het registratiemiddel bevat of heeft de volgende eigenschappen:
a.
een bewegingsdetectie van het registratiemiddel;
b.
een locatiebepaling met een nauwkeurigheid van ten minste 25 meter;
c.
de functionaliteit om de laatst bekende locatie vast te houden;
d.
de functionaliteit om op basis van de locatiebepaling een afgelegde afstand te bepalen met een maximale afwijking van 15%;
e.
een tijdsbepaling met een nauwkeurigheid van ten minste 1 seconde en synchronisatie met een geijkte externe tijdfunctie;
f.
voorzieningen om de bestuurder te authentiseren als genoemd in artikel 6;
g.
de functionaliteit om unieke identificatiecodes van diensten, ritten, pauzes en gebeurtenissen te genereren;
voorzieningen die taxivervoergegevens realtime doorsturen naar de centrale applicatie;
j.
voorzieningen die ervoor zorgen dat er geen taxivervoergegevens verloren kunnen gaan;
k.
de functionaliteit voor de bestuurder om alleen auto's te kunnen opgeven die de vervoerder voor hem heeft toegestaan;
l.
de functionaliteit voor de bestuurder om zich aan te kunnen melden voor vervoerders die hem dat toestaan.
2
Het is niet toegestaan het registratiemiddel op een wijze te gebruiken die maakt dat taxivervoergegevens kunnen worden gewijzigd of verwijderd voordat deze zijn aangeleverd in de CDT.
Artikel
9
(Centrale applicatie)
1
Het aanleveren van taxivervoergegevens vanaf het registratiemiddel aan de CDT vindt plaats via een centrale applicatie.
2
De centrale applicatie bevat of heeft de volgende eigenschappen:
a.
een functionaliteit om alle ontvangen gegevens direct en ongewijzigd door te sturen naar de CDT Meldingen API;
b.
een functionaliteit die ervoor zorgt dat berichten in chronologische volgorde van registratie tijdens de werkzaamheden aan boord van de auto waarmee taxivervoer wordt verricht worden aangeboden aan de CDT Meldingen API;
c.
een functionaliteit die maakt dat een volgend bericht aan de CDT Meldingen API pas wordt aangeboden als het voorgaande bericht succesvol is verwerkt.
Artikel
10
(Informatiebeveiliging)
1
De vervoerder maakt gebruik van een ICT-oplossing en een organisatie die zijn gecertificeerd voor ISO 27001. De certificatie wordt verricht door een certificerende instelling die is geaccrediteerd door de Raad voor Accreditatie of een andere accreditatie instelling die is erkend in een lidstaat van de Europese Unie.
2
De certificering, bedoeld in het eerste lid, heeft als werkingsgebied alle functionaliteit die gegevens levert aan de CDT Meldingen API. De functionaliteit omvat ten minste alle registratiemiddelen en de centrale applicatie.
§
4
Overgangs- en slotbepalingen
Artikel
11
(Inwerkingtreding)
Deze regeling treedt in werking met ingang van 1 juli 2025.
Artikel
12
(Citeertitel)
Deze regeling wordt aangehaald als: Regeling centrale database taxivervoer.
Deze regeling zal met de toelichting in de Staatscourant worden geplaatst.
De Staatssecretaris van Infrastructuur en Waterstaat – Openbaar Vervoer en Milieu,C.A.Jansen
Bijlage
Technische beschrijving van de berichtenuitwisseling voor het aanleveren van taxivervoergegevens aan de CDT Meldingen API (koppelvlakspecificatie CDT)
Aanmelden dienst (relateren chauffeur, ondernemer en voertuig)
2.2
Aanmelden rit en aanmelden pauze
2.3
Afmelden rit en afmelden pauze
2.4
Afmelden dienst
2.5
Aanmelden ICT-dienstverlener
2.6
Afmelden ICT-dienstverlener
2.7
Valideren van chauffeur
2.8
Opvragen van openstaande diensten en verrichtingen
2.9
Melden van gebeurtenissen van het registratiemiddel chauffeur
2.10
Opvragen chauffeursnummer
3
BERICHTEN
3.1
Statusovergangen
3.2
Generieke berichtgegevens in headers
3.3
Functionele berichtgegevens
3.3.1
Chauffeur
3.3.2
Rijbewijs
3.3.3
Authenticatie
3.3.4
Ondernemer
3.3.5
Voertuig
3.3.6
Andere werkzaamheden
3.3.7
Locatie
3.4
Aanmelden dienst (relateren chauffeur, ondernemer en voertuig)
3.5
Afmelden dienst
3.6
Aanmelden rit
3.7
Afmelden rit
3.8
Aanmelden pauze
3.9
Afmelden pauze
3.10
Aanmelden ICT-dienstverlener
3.11
Afmelden ICT-dienstverlener
3.12
Valideren chauffeur
3.13
Opvragen van openstaande diensten en verrichtingen
3.14
Melden van gebeurtenissen van het registratiemiddel chauffeur
3.15
Opvragen chauffeursnummer
3.16
Foutmeldingscodes
3.16.1
Foutmeldingen wegens headers
3.16.2
Foutmeldingen wegens fouten in het bericht zelf
3.16.3
Foutmeldingen wegens verwerken inhoud
4
TECHNISCHE EISEN
4.1
Conventies
4.1.1
JSON conventies
4.1.2
Encoding
4.1.3
Hoofdlettergevoeligheid
4.1.4
Datum/tijd
4.1.5
Berichtenverkeer
4.1.6
Endpoints
4.2
Actualiteit van data
4.3
Beschikbaarheid en performance
4.3.1
Beschikbaarheid
4.3.2
Performance
5
LOGGING EN MONITORING VERBINDING
5.1
Logging
5.2
Connectie-monitoring
6
FOUTAFHANDELING
6.1
Algemeen
6.2
Error in aanroep dienstgerelateerde endpoints
6.3
Error in aanroep /verbinding
6.4
Duplicaat detectie
7
AUTHENTICATIE EN INFORMATIEBEVEILIGING
7.1
Authenticatie
7.1.1
PKI Certificaten
7.1.2
Authenticatie rijbewijs
7.1.3
Authenticatie kentekenbewijs
7.2
Informatiebeveiliging
7.2.1
Transport Layer Security (TLS)
7.2.2
API-keys
7.3
Headers
1
Inleiding
Deze koppelvlakspecificatie geeft een beschrijving van de volgende functies van de CDT-Meldingen-API:
1.)
Het aanleveren van diensten, ritten en pauzes door de ondernemer;
2.)
Het valideren van chauffeursgegevens;
3.)
Het opvragen van openstaande diensten en verrichtingen binnen de CDT;
4.)
Het aan- en afmelden van ICT-dienstverleners door ondernemers;
5.)
Het melden van gebeurtenissen van het registratiemiddel chauffeur gerelateerd aan een dienst.
6.)
Het opvragen van het chauffeursnummer van een taxichauffeur op basis van het nummer van zijn Nederlandse rijbewijs.
1.1
Context
De chauffeur maakt gebruik van een Registratiemiddel Chauffeur om realtime relevante informatie over de uitvoering van taxivervoer te registreren voor de ondernemer in de centrale applicatie, die de gegevens realtime levert aan de CDT. Voor de uitwisseling van berichten met de ILT is de CDT-Meldingen-API (op basis van REST) ontwikkeld die aangeroepen dient te worden door de Centrale Applicatie.
1.2
Doel
Dit document is een bijlage bij de Regeling CDT. Het doel van dit document is om aan partijen die gebruik willen maken van de CDT Meldingen API inzicht te verschaffen in de functies en werking van de CDT-Meldingen-API.
2
Processen
In deze koppelvlakspecificatie wordt de term ‘dienst’ gebruikt zoals dat in het dagelijks spraakgebruik wordt gedaan. De betekenis van dienst in dit document is daardoor niet de definitie van Dienst in art 1.7 eerste lid onder c van de Arbeidstijdenwet. Met ‘dienst’ wordt in deze koppelvlakspecificatie ‘de werkzaamheden als taxichauffeur aan boord van de auto waarmee taxivervoer wordt verricht’ bedoeld.
De volgende processen zijn in scope voor de aanlevering bij de CDT:
1.
Aanmelden dienst (relateren chauffeur, ondernemer en voertuig);
2.
Melden andere werkzaamheden van de chauffeur voorafgaand aan de dienst;
3.
Aanmelden rit of pauze;
4.
Afmelden rit of pauze;
5.
Afmelden dienst;
6.
Aanmelden ICT-dienstverlener door ondernemer;
7.
Afmelden ICT-dienstverlener door ondernemer;
8.
Valideren van chauffeur;
9.
Opvragen van openstaande diensten en verrichtingen;
10.
Doorgeven van gebeurtenissen van het registratiemiddel chauffeur;
11.
Opvragen van chauffeursnummer.
2.1
Aanmelden dienst (relateren chauffeur, ondernemer en voertuig)
Preconditie
De ondernemer heeft ervoor gezorgd dat:
1.
De ICT-dienstverlener is aangemeld bij de CDT Meldingen API;
2.
Het voertuig is gevalideerd;
3.
De chauffeur is gevalideerd;
4.
De chauffeur toegang heeft tot het 'registratiemiddel chauffeur'.
Proces
De chauffeur:
1.
Authenticeert zich met een toegestane authenticatiemethode;
2.
Voegt eventueel begin- en eindtijden in van andere werkzaamheden die voorafgaand aan de dienst zijn uitgevoerd;
3.
Meldt de dienst, met daarop de ondernemer en het voertuig, via het registratiemiddel chauffeur aan bij de centrale applicatie, die vervolgens de dienst onmiddellijk aanmeldt bij de CDT-Meldingen-API.
Postconditie
De aanmelding van de dienst is geregistreerd voor de chauffeur, het voertuig en de ondernemer in de centrale applicatie en in de CDT. De optionele aanmelding van de andere werkzaamheden is geregistreerd voor de chauffeur.
2.2
Aanmelden rit en aanmelden pauze
Preconditie
•
De dienst waarbinnen de rit of pauze plaatsvindt, is aangemeld en geregistreerd in de centrale applicatie en de CDT;
•
Bij aanmelden pauze: er zijn geen niet-afgemelde ritten of pauzes binnen deze dienst;
•
Bij aanmelden rit: er zijn geen niet-afgemelde pauzes binnen deze dienst;
Proces
•
De chauffeur meldt via het registratiemiddel chauffeur de rit of pauze aan bij de centrale applicatie, die vervolgens de rit of pauze onmiddellijk aanmeldt bij de CDT-Meldingen API.
•
Bij het aanmelden van een rit is de locatie verplicht. Indien er geen actuele locatie beschikbaar is wordt de laatst bekende locatie doorgegeven.
Postconditie
De aanmelding van de rit of pauze is geregistreerd binnen de dienst van de chauffeur in de centrale applicatie en de CDT.
2.3
Afmelden rit en afmelden pauze
Preconditie
De rit of pauze is geregistreerd in de centrale applicatie en de CDT.
Proces
•
De chauffeur meldt via het registratiemiddel chauffeur de rit of pauze af bij de centrale applicatie, die vervolgens de rit of pauze onmiddellijk afmeldt bij de CDT-Meldingen-API.
Postconditie
De afmelding van de rit of pauze is geregistreerd binnen de dienst voor de chauffeur en de ondernemer in de centrale applicatie en de CDT.
2.4
Afmelden dienst
Preconditie
De dienst is geregistreerd en alle ritten en pauzes binnen de dienst zijn afgemeld in de centrale applicatie en de CDT.
Proces
De chauffeur meldt via het registratiemiddel chauffeur de dienst af bij de centrale applicatie, die vervolgens de dienst onmiddellijk afmeldt bij de CDT-Meldingen-API.
Postconditie
De afmelding van de dienst is geregistreerd in de centrale applicatie en de CDT.
2.5
Aanmelden ICT-dienstverlener
Preconditie
De ondernemer neemt een ICT-oplossing af bij de ICT-dienstverlener en heeft de ICT-dienstverlener niet aangemeld bij de CDT Meldingen API.
Proces
De centrale applicatie stuurt de aanmelding van de ondernemer voor de ICT-dienstverlener naar de CDT Meldingen API.
Postconditie
De ICT-dienstverlener is door de ondernemer aangemeld bij de CDT Meldingen API.
2.6
Afmelden ICT-dienstverlener
Preconditie
De ondernemer is gestopt met het afnemen van de ICT-oplossing van de ICT-dienstverlener en;
De ICT-dienstverlener is door de ondernemer aangemeld bij de CDT Meldingen API.
Proces
De centrale applicatie stuurt de afmelding van de ondernemer voor de ICT-dienstverlener naar de CDT Meldingen API.
Postconditie
De ICT-dienstverlener is door de ondernemer afgemeld bij de CDT Meldingen API.
2.7
Valideren van chauffeur
Preconditie
Ondernemer beschikt niet over de informatie of een chauffeur bevoegd is.
Proces
Ondernemer valideert via de Centrale applicatie de chauffeursgegevens bij de CDT.
NB: alleen bij validatiecode 0 worden de chauffeursgegevens als gevalideerd beschouwd.
Postconditie
Ondernemer beschikt over de informatie of de opgegeven chauffeursgegevens van een bevoegde chauffeur zijn.
2.8
Opvragen van openstaande diensten en verrichtingen
Preconditie
Centrale applicatie beschikt niet over de informatie welke diensten en verrichtingen langer dan een opgegeven duur open staan in de CDT.
Proces
Centrale applicatie vraagt diensten en verrichtingen op die langer dan een gespecificeerde tijdsduur (minimaal 24 uur) openstaan bij de CDT.
Postconditie
Centrale applicatie beschikt over de informatie met betrekking tot welke diensten en verrichtingen langer dan de gespecificeerde tijdsduur open staan in de CDT.
2.9
Melden van gebeurtenissen van het registratiemiddel chauffeur
Gebeurtenissen van het registratiemiddel chauffeur zijn meldingen (M). Een nadere toelichting hierop is te vinden in paragraaf 3.14 van dit document.
Preconditie
De dienst waaraan de gebeurtenis is gerelateerd, is aangemeld en geregistreerd in de centrale applicatie en de CDT.
Proces
Het registratiemiddel chauffeur meldt de gebeurtenis bij de centrale applicatie, die vervolgens de gebeurtenis onmiddellijk meldt bij de CDT-Meldingen-API.
Postconditie
De gebeurtenis is geregistreerd in de centrale applicatie en de CDT.
2.10
Opvragen chauffeursnummer
Het chauffeursnummer staat niet vermeld op de beschikking bij chauffeurskaarten die zijn uitgegeven voor 2025. Om het chauffeursnummer te achterhalen kan op basis van de gegevens van een Nederlands rijbewijs het chauffeursnummer opgevraagd worden bij de CDT Meldingen API.
Preconditie
Chauffeur en ondernemer beschikken niet over het chauffeursnummer en chauffeur heeft een geldig Nederlands rijbewijs en zijn BSN is geregistreerd bij Kiwa.
Proces
Ondernemer vraagt op basis van het Nederlandse rijbewijs van de chauffeur het chauffeursnummer op bij de CDT.
Postconditie
Indien de chauffeur beschikt over een geldige taxibevoegdheid, levert de CDT het chauffeursnummer terug aan de ondernemer.
NB: voor chauffeurs die geen Nederlands rijbewijs hebben of die bij KIWA niet met een BSN geregistreerd zijn is het niet mogelijk het chauffeursnummer op basis van rijbewijsgegevens op te vragen. Deze chauffeurs ontvangen het chauffeursnummer per brief van KIWA, en dienen het chauffeursnummer door te geven aan de ondernemer.
3
Berichten
Berichten bestaan uit generieke berichtgegevens (metagegevens) en de inhoud van het bericht zelf. ILT heeft ervoor gekozen om de metagegevens als headers in het bericht op te nemen.
3.1
Statusovergangen
De logische samenhang tussen de berichten en de status van een dienst en verrichting is in onderstaande figuur weergegeven. De berichten ‘opvragen openstaande diensten’ en ‘valideren chauffeurs’ komen niet voor in onderstaand figuur omdat ze geen invloed hebben op de status van diensten en verrichtingen.
Regels:
•
Diensten mogen alleen worden aangemeld door een aangemelde ICT-dienstverlener;
•
Het aanmelden van een verrichting (rit of pauze) vereist een aangemelde dienst;
•
Het aanmelden van een gebeurtenis vereist een aangemelde dienst;
•
Om een dienst te kunnen afmelden moeten alle verrichtingen binnen die dienst afgemeld zijn;
•
Gebeurtenissen kunnen worden gemeld tijdens een dienst, ongeacht of er een verrichting plaats vindt;
•
De volgende regels gelden bij overlappende verrichtingen:
○
Overlappende ritten zijn toegestaan;
○
Tijdens een rit kan geen pauze worden aangemeld;
○
Tijdens een pauze kan geen rit worden aangemeld.
•
Een pauze kan alleen gemeld worden met een aanmeldtijdstip dat ligt na de laatst afgemelde verrichting.
3.2
Generieke berichtgegevens in headers
De velden in de onderstaande tabel staan de bericht header.
Dienstverlener
UUID
a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11
Door ILT uitgegeven sleutel die de aanleverende ICT-dienstverlener uniek identificeert bij de CDT-Meldingen-API.
ext_key
UUID
a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11
Unieke sleutel voor toegang tot de API-gateway
Bericht-Id
UUID
a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11
Identificatie van een bericht.
NB: dit dient gegenereerd te worden bij het verzenden van het bericht.
Verzendtijdstip
date-time in UTC conform IETF RFC3339
2023-03-31T14:55:44Z of
2023-03-31T14:55:44.444Z
Verzendtijdstip van bericht van ICT-dienstverlener naar ILT.
NB: dit tijdstip dient bij iedere verzendpoging geactualiseerd te worden.
Softwareversie-Registratiemiddel
String(20)1
v12.23.124
Softwareversie van het registratiemiddel.
Softwareversie-Centrale-Applicatie
String(20)
v2.2.9
Softwareversie van de Centrale applicatie
1 Softwareversie-Registratiemiddel mag een empty string zijn als het bericht niet afkomstig is van een ‘registratiemiddel chauffeur’.
3.3
Functionele berichtgegevens
De velden in de onderstaande tabel kunnen op een bericht voorkomen (in de message body), per bericht is beschreven welke van deze velden voorkomen. Daarnaast staan in paragrafen 3.3.1 tot en met 3.3.7 objecten die in berichten kunnen voorkomen.
id
UUID
a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11
Identificatie van een dienst, verrichting of gebeurtenis
NB: dit dient gegenereerd te worden bij het ontstaan van de dienst, verrichting of gebeurtenis.
aanmeldtijdstip
date-time in UTC conform IETF RFC3339
2023-03-31T14:55:44Z of
2023-03-31T14:55:44.444Z
Het tijdstip waarop de dienst of verrichting is gestart.
NB: dit is het tijdstip op het registratiemiddel.
afmeldtijdstip
date-time in UTC conform IETF RFC3339
2023-03-31T14:55:44Z of
2023-03-31T14:55:44.444Z
Het tijdstip waarop de dienst of verrichting is beëindigd.
NB: dit is het tijdstip op het registratiemiddel.
ritprijs
Integer(6)
10170
Totale eindprijs van de afgelegde rit in eurocenten. Dit is exclusief fooi.
afstand
Numeric (4,1)
12,1
Afgelegde afstand van rit
registratietijdstip
date-time in UTC conform IETF RFC3339
2023-03-31T14:55:44Z of
2023-03-31T14:55:44.444Z
Het tijdstip waarop registratie plaatsvindt op het registratiemiddel.
gebeurtenistijdstip
date-time in UTC conform IETF RFC3339
2023-03-31T14:55:44Z of
2023-03-31T14:55:44.444Z
Tijdstip dat de gebeurtenis plaatsvindt op het registratiemiddel.
gebeurteniscode
String(4)
M106
code uit tabel in paragraaf 3.14
Regels:
•
Bij het bericht is aangegeven welke velden verplicht zijn;
•
Bericht wordt afgewezen als velden niet het juiste formaat of opmaak hebben;
•
Bericht wordt afgewezen als verplichte velden ontbreken;
•
Bericht wordt afgewezen als andere dan toegestane velden aanwezig zijn;
•
Bericht wordt afgewezen als toegestane velden vaker dan gespecificeerd voorkomen.
Naast de velden in bovenstaande tabel kunnen ook objecten worden verstuurd. Deze staan in de volgende paragrafen beschreven.
3.3.1
Chauffeur
chauffeursnummer
String(8)
^T\d{7}$
T0012345
Chauffeursnummer zoals uitgegeven door KIWA
gevalideerd
boolean
true
indicatie of rijbewijs bij CDT Meldingen API gevalideerd is. Deze mag alleen op true worden gezet als op aanroep van POST https://[host]/v2/chauffeurs/valideren validatiecode 0 is teruggegeven voor de combinatie chauffeur/ondernemer.
rijbewijs
object
zie paragraaf 3.3.2
Voorbeeld:
"chauffeur": {
"chauffeursnummer": "T0012345",
"gevalideerd": true,
"rijbewijs": {
"land": "NL",
"nummer": "123456789"
}
}
3.3.2
Rijbewijs
land
string2
^[A-Z]{2]$
NL
Landcode volgens ISO3166-1 alpha-2
rijbewijsnummer
string(16)
^[0-9a-zA-Z]{1,16}$
1234567890
Een Nederlands rijbewijsnummer bestaat uit 10 cijfers, andere landen kunnen afwijken. Streepjes, spaties en punten worden weggelaten.
Voorbeeld:
"rijbewijs": {
"Land": "NL",
"rijbewijsnummer": "123456789"
}
3.3.3
Authenticatie
middel
string{4}
RBNL|BIO|
2FA|geen
RBNL
RBNL = Nederlands rijbewijs
BIO = Biometrie
2FA = 2-factor authenticatie
geen = chauffeur is niet geauthenticeerd (NB: alleen te gebruiken bij aanmelden dienst door vervoerder bij aanlevering achteraf).
kenmerk
string(32)
–
1234565677
vingerafdruk
gezichtsherkenning
wachtwoord-SMS
wachtwoord-koppelcode
pincode-SMS
pincode-koppelcode
geen
Bij RBNL → rijbewijsnummer
Bij BIO → vingerafdruk, gezichtsherkenning
Bij 2FA → wachtwoord-SMS,
wachtwoord-koppelcode,
pincode-SMS,
pincode-koppelcode
Bij geen → geen.
Voorbeelden:
"authenticatie": {
"middel": "RBNL",
"kenmerk": "2090710264"
}
"authenticatie": {
"middel": "BIO",
"kenmerk": "gezichtsherkenning"
}
"authenticatie": {
"middel": "2FA",
"kenmerk": "wachtwoord-SMS"
}
"authenticatie": {
"middel": "geen",
"kenmerk": "geen"
}
3.3.4
Ondernemer
kiwaNummer
string(7)
^P\d{4,6}$
P123456
nummer van KIWA taxivergunning
kvkNummer
string(8)
^\d{8}$
12345678
Kamer van Koophandel nummer
Voorbeeld:
"ondernemer": {
"kvkNummer": "12345678",
"kiwaNummer": "P1234"
}
3.3.5
Voertuig
kenteken
string(6)
^[0-9A-Z]{6}$
P390HV
kenteken van het voertuig
validatiemethode
string(1)
K|N
K
‘K’: kentekenkaart gelezen
‘N’: niet gevalideerd
validatiedatum
string(10)
^\d{4}-\d{2}-\d{2}$
2024-03-04
datum waarop validatie is uitgevoerd, format YYYY-MM-DD. Als validatie-methode = ‘N’ dan de huidige datum gebruiken.
Voorbeeld:
"voertuig": {
"kenteken": "P390HV",
"validatiemethode": "N",
"validatiedatum": "2024-03-04"
}
3.3.6
Andere werkzaamheden
begintijdstip
date-time in UTC conform IETF RFC3339
2023-03-31T14:55:44Z of
2023-03-31T14:55:44.444Z
datum en tijdstip waarop andere werkzaamheden zijn gestart
eindetijdstip
date-time in UTC conform IETF RFC3339
2023-03-31T14:55:44Z of
2023-03-31T14:55:44.444Z
datum en tijdstip waarop andere werkzaamheden zijn geëindigd
Voorbeeld:
"andereWerkzaamheden": [
{
"begintijdstip": "2023-03-31T14:44:55.000Z",
"eindetijdstip": "2023-03-31T15:44:55.000Z"
},
{
"begintijdstip": "2023-03-31T18:44:55.000Z",
"eindetijdstip": "2023-03-31T19:44:55.000Z"
}
]
3.3.7
Locatie
breedtegraad
string
^[-+]?(90(\\.0{4,6})?|([1-8]?\\d(\\.\\d{4,6})?))$
5.100056
geografische breedtegraad met 4 tot 6 cijfers achter de punt
geografische lengtegraad met 4 tot 6 cijfers achter de punt
Voorbeeld:
"locatie": {
"breedtegraad": "5.10005",
"lengtegraad": "52.08649"
}
3.4
Aanmelden dienst (relateren chauffeur, ondernemer en voertuig)
Use cases:
•
Aanmelden dienst bij aanvang van de werkzaamheden aan boord van de auto waarmee taxivervoer wordt verricht, eventueel met voorafgaande andere werkzaamheden.
Bij aanmelden dienst bevat het bericht naast alle generieke berichtgegevens de volgende functionele berichtgegevens:
id (van de dienst)
ja
chauffeur
ja
authenticatie
ja
ondernemer
ja
voertuig
ja
aanmeldtijdstip
ja
registratietijdstip
ja
andereWerkzaamheden
nee
Response sunny day: ‘201 CREATED’
Velden in de response body:
data
id
Meldingen in de onderstaande tabel zijn mogelijk bij een '201 CREATED' resultaatcode.
201
DF00
Er zijn [#] diensten actief voor de chauffeur bij de ICT-dienstverlener.
Er is voor de opgegeven chauffeur nog een niet-afgesloten dienst bij ILT geregistreerd bij deze ICT-dienstverlener. NB: deze melding wordt niet getoond als de dienst voor de chauffeur open staat bij een andere ICT-dienstverlener.
201
DF06
‘voertuig.kenteken’ is in gebruik op een andere dienst bij de ICT-dienstverlener.
Er is voor het opgegeven voertuig nog een niet-afgesloten dienst bij ILT geregistreerd bij de ICT-dienstverlener. NB: deze melding wordt alleen teruggegeven als de dienst met het voertuig afkomstig is van de aanleverende ICT-dienstverlener.
201
DF07
‘chauffeur’ is niet gevalideerd terwijl deze als gevalideerd is gemarkeerd.
Een chauffeur mag alleen als gevalideerd worden gemeld als een geslaagde validatie is uitgevoerd.
201
DF08
‘ICT-dienstverlener’ is niet aangemeld voor ondernemer
Een ondernemer moet aanmelden welke ICT-dienstverlener voor hem levert.
Bij een afwijzing zijn de meldingen te vinden in paragraaf 3.16.
Response bij openstaande diensten: ‘201 CREATED’
gegevens van openstaande dienst(en) bij de inzendende ICT-dienstverlener staan in de message body.
Velden in de response body:
data
id (van de aangemelde dienst)
meldingen (optioneel, één of meer)[
code
tekst
details (optioneel, zal voorkomen bij DF00)
openstaandeDiensten (één of meer) [
id
aanmeldtijdstip
openstaandeVerrichtingen (optioneel, één of meer)[
id
aanmeldtijdstip
]
]
]
3.5
Afmelden dienst
Use cases:
•
Afmelden dienst bij einde van de werkzaamheden aan boord van de auto waarmee taxivervoer wordt verricht.
In de message body wordt de te valideren chauffeur opgegeven met zijn chauffeursnummer en Nederlandse rijbewijs, en de ondernemer die de validatie uitvoert.
chauffeur
ja
ondernemer
ja
NB: het chauffeursobject heeft het onderdeel ‘gevalideerd’. De waarde hiervan moet false zijn bij deze opvraging.
Response sunny day: ‘200 OK’
Velden in de response body:
data
validaties:[
validatiecode
validatieomschrijving
]
0
‘chauffeur.chauffeursnummer’ is van bevoegde chauffeur;
‘chauffeur.rijbewijs.rijbewijsnummer’ is van een geldig rijbewijs en beiden zijn van dezelfde chauffeur
‘chauffeur.chauffeursnummer’ is van een bevoegde chauffeur
1
‘chauffeur.chauffeursnummer’ is van een andere chauffeur dan ‘chauffeur.rijbewijs.rijbewijsnummer’
niet van toepassing
2
‘chauffeur.chauffeursnummer’ onbekend
‘chauffeur.chauffeursnummer’ onbekend
3
‘chauffeur.rijbewijs.rijbewijsnummer’ onbekend
niet van toepassing
4
‘chauffeur.chauffeursnummer’ is van onbevoegde chauffeur
‘chauffeur.chauffeursnummer’ is van onbevoegde chauffeur
5
rijbewijs is ongeldig
niet van toepassing
Als op deze validatie de validatiecode 0 is geretourneerd mag bij aanmelden dienst voor deze chauffeur met chauffeur.chauffeursnummer en chauffeur.rijbewijs.nummer chauffeur.gevalideerd op true worden gezet. Alle voorgaande gebruikte combinaties van chauffeur.chauffeursnummer met chauffeur.rijbewijs.nummer gelden vanaf dat moment niet meer als gevalideerd.
Bij een afwijzing zijn de meldingen te vinden in paragraaf 3.16.
3.13
Opvragen van openstaande diensten en verrichtingen
Geeft alle niet-afgemelde diensten met eventueel niet-afgemelde verrichtingen met een aanmeldtijdstip langer dan x uur geleden voor ICT-dienstverlener Y, waarbij x een defaultwaarde heeft van 24, dus als ouderdan wordt weggelaten wordt 24 gebruikt. Een lagere waarde dan 24 wordt genegeerd, in plaats daarvan wordt 24 gebruikt.
Headers: Softwareversie-Registratiemiddel mag leeg (empty string) zijn indien de opvraging afkomstig is van centrale applicatie.
Response sunny day: ‘200 OK’
Velden in de response body:
data
openstaandeDiensten (kunnen er meer zijn) [
id [
aanmeldtijdstip
openstaandeVerrichtingen (optioneel, kunnen er meer zijn) [
id,
aanmeldtijdstip
]
]
Als er geen openstaande diensten zijn dan krijgt de aanroep een ‘204 No Content’ response zonder message body.
3.14
Melden van gebeurtenissen van het registratiemiddel chauffeur
Use case:
•
Een gebeurtenis op het registratiemiddel chauffeur melden bij de ILT.
Endpoint: (alle gebeurtenissen worden als dienstgebonden beschouwd)
1 zie tabel hieronder wanneer dit veld verplicht is.
De codes voor Meldingen zijn verplicht.
Meldingen
M1001
Authenticatiepoging voor en tijdens dienst niet succesvol.
authenticatie
M101
Uitval van registratiemiddel chauffeur tijdens dienst.
NB: deze melding zal pas kunnen worden gegenereerd als het registratiemiddel na uitval opnieuw wordt opgestart.
M102
Geen positiebepaling langer dan 3 minuten.
locatie (laatst bekende locatie)
M103
Positiebepaling succesvol na gebeurtenis M102.
locatie
M104
Tijd op registratiemiddel langer dan 10 minuten niet gesynchroniseerd.
M105
Tijd op registratiemiddel gesynchroniseerd na melding synchronisatieprobleem.
M106
Geen beweging gedetecteerd langer dan 1 minuut tijdens verrichting ‘rit’ terwijl positiebepaling beweging suggereert.
M107
beweging gedetecteerd terwijl positiebepaling beweging suggereert na melding M106.
M1082
Geen gegevensverbinding langer dan 1 minuut met registratiemiddel chauffeur.
M1092
Gegevensverbinding hersteld met registratiemiddel chauffeur na onderbreking.
M1102
Dienst afgemeld door ondernemer
M1112
Verrichting afgemeld door ondernemer
M112
Per ongeluk gestarte dienst/verrichting afgesloten.
NB: de functionaliteit om een per ongeluk gestarte dienst of verrichting af te sluiten is optioneel. Bij het toepassen van deze functionaliteit is het verzenden van deze gebeurteniscode verplicht.
M113
Ritprijs is handmatig opgevoerd.
NB: deze melding is niet nodig bij contract- of groepsvervoer, waarbij de waarde van ‘ritprijs’ 0 mag zijn.
1 Melding doorgeven na de eerstvolgende geslaagde aanmelding dienst op het registratiemiddel chauffeur
2 Melding is normaliter afkomstig van de Centrale Applicatie.
NB: bij M101 en M104 dient het gebeurtenistijdstip het tijdstip te zijn waarop de fout voor het eerst is geconstateerd en het registratietijdstip het tijdstip waarop de fout is gemeld vanuit het detecterende apparaat.
Response sunny day: ‘201 OK’
Velden in de response body:
data
id
Bij een afwijzing zijn de meldingen te vinden in paragraaf 3.16.
3.15
Opvragen chauffeursnummer
Use case:
•
Opvragen van een chauffeursnummer op basis van een Nederlands rijbewijsnummer.
Indien voor het opgegeven Nederlandse rijbewijs het chauffeursnummer kan worden gevonden wordt dit teruggegeven. Indien een niet-Nederlands rijbewijs wordt opgegeven zal geen chauffeursnummer worden gevonden.
Headers: Softwareversie-Registratiemiddel mag leeg (empty string) zijn indien de opvraging afkomstig is van centrale applicatie.
Velden:
rijbewijs
Ja
Response als gevonden: ‘200 OK’
Velden in de response body:
data
chauffeursnummer
Bij een afwijzing of geen gevonden resultaat zijn de meldingen te vinden in paragraaf 3.16.
3.16
Foutmeldingscodes
De CDT Meldingen API kent de onderstaande foutmeldingscodes. Bij iedere errorcode is de http-status code weergegeven en op welke aanroepen deze kan komen.
Codering error codes:
Hxxx
technische fout in (een van de) header(s).
HFxx
functionele fout in (een van de) header(s).
Gxxx
generieke (technische) fout.
DFxx
functionele fout in dienstbericht.
VFxx
functionele fout in verrichtingbericht.
BFxx
functionele fout in gebeurtenisbericht.
OFxx
functionele fout in opvraging
Fouten worden teruggegeven in de response body in het onderstaande format:
data
foutmelding
aantal
fouten [
code
tekst
details (optioneel)
openstaandeVerrichtingen (één of meer)[
id
aanmeldtijdstip
]
]
3.16.1
Foutmeldingen wegens headers
De onderstaande meldingen kunnen op alle aanroepen worden teruggegeven:
400
H000
Ontbrekende header <headernaam>.
Dienstverlener, Bericht-Id, Softwareversie-Registratiemiddel, Softwareversie-Centrale-Applicatie of Verzendtijdstip ontbreekt.
400
H001
Waarde van ‘Bericht-Id’ voldoet niet aan de opmaak.
Moet UUID zijn
400
H002
Waarde van ‘Verzendtijdstip’ voldoet niet aan de opmaak.
IETF RFC3339 ‘date-time’ specificatie.
400
H003
Waarde van ‘Verzendtijdstip’ is in de toekomst.
Een bericht kan niet in de toekomst zijn verzonden.
400
H004
Waarde van ‘Softwareversie-Registratiemiddel’ voldoet niet aan de opmaak.
^[0-9A-Za-z.-]{2,20}$, mag in specifieke gevallen empty string zijn.
400
H005
Waarde van ‘Softwareversie-Centrale-Applicatie’ voldoet niet aan de opmaak.
^[0-9A-Za-z.-]{2,20}$
400
H006
Waarde van ‘Dienstverlener’ voldoet niet aan de opmaak.
Moet UUID zijn
400
HF00
Onbekende Dienstverlener.
Dienstverlenercode is niet actief of onbekend.
400
HF10
Bericht-Id is niet uniek.
De Bericht-Id op de header moet uniek zijn
NB: Door de manier waarop de validaties worden uitgevoerd komen de header-foutmeldingen alleen voor op berichten die geen andere foutmeldingen geven.
Gegevens meldingen:
A
Aanmelden dienst
B
Afmelden dienst
C
Aanmelden rit
D
Afmelden rit
E
Aanmelden pauze
F
Afmelden pauze
G
Aanmelden ICT-dienstverlener
H
Valideren chauffeur
I
Melden gebeurtenissen
J
Opvragen chauffeursnummer
NB: ‘Opvragen openstaande diensten’ en ‘afmelden ICT-dienstverlener’ zijn niet opgenomen in de tabellen omdat deze beide geen message body bevatten waarop de foutcodes betrekking hebben.
3.16.2
Foutmeldingen wegens fouten in het bericht zelf
400
G000
Ongeldige JSON.
Geldt voor het hele bericht: ongeldige JSON formattering.
X
X
X
X
X
X
X
X
X
X
400
G001
Dubbel veld.
Gegevens moeten éénduidig zijn, het is niet toegestaan hetzelfde gegeven meer dan één keer in een bericht op te nemen.
X
X
X
X
X
X
X
X
X
X
400
G010
‘aanmeldtijdstip’ ontbreekt.
verplicht veld
X
X
X
400
G011
Waarde van ‘aanmeldtijdstip’ voldoet niet aan de opmaak.
De datum/tijd is in UTC, ISO-format yyyy-MM-ddThh:mm:ss.sssZ
X
X
X
400
G012
Waarde van ‘aanmeldtijdstip’ is in de toekomst.
De datum/tijd mag niet in de toekomst zijn.
X
X
X
400
G020
‘registratietijdstip’ ontbreekt.
verplicht veld
X
X
X
X
X
X
X
400
G021
Waarde van ‘registratietijdstip’ voldoet niet aan de opmaak.
De datum/tijd is in UTC, ISO-format yyyy-MM-ddThh:mm:ss.sssZ
X
X
X
X
X
X
X
400
G022
Waarde van ‘registratietijdstip’ is in de toekomst.
De datum/tijd mag niet in de toekomst zijn.
X
X
X
X
X
X
X
400
G030
‘afmeldtijdstip’ ontbreekt.
Verplicht veld
X
X
X
400
G031
Waarde van ‘afmeldtijdstip’ voldoet niet aan de opmaak.
De datum/tijd is in UTC, ISO-format yyyy-MM-ddThh:mm:ss.sssZ
X
X
X
400
G032
Waarde van ‘afmeldtijdstip’ is in de toekomst.
De datum/tijd mag niet in de toekomst zijn.
X
X
X
400
G040
‘id’ ontbreekt.
verplicht veld
X
X
X
X
400
G041
Waarde van ‘id’ voldoet niet aan de opmaak.
UUID
X
X
X
X
400
G050
Waarde van padparameter ‘dienst’ voldoet niet aan de opmaak.
UUID
X
X
X
X
X
X
400
G060
‘chauffeur’ ontbreekt.
Verplicht
X
X
400
G061
‘chauffeur.chauffeursnummer’ ontbreekt.
Verplicht veld
X
X
400
G062
Waarde van ‘chauffeur.chauffeursnummer’ voldoet niet aan de opmaak.
Format ^T\d{7}$, bijv. T0012345.
X
X
400
G063
‘chauffeur.gevalideerd’ ontbreekt.
Verplicht veld
X
400
G064
Waarde van ‘chauffeur.gevalideerd’ voldoet niet aan de opmaak.
Boolean, true of false
X
400
G070
‘chauffeur.rijbewijs’ ontbreekt.
verplicht
X
X
X
400
G071
‘chauffeur.rijbewijs.rijbewijsnummer’ ontbreekt.
Verplicht veld
X
X
X
400
G072
Waarde van ‘chauffeur.rijbewijs.rijbewijsnummer’ voldoet niet aan de opmaak.
Veld is maximaal 16 alfanumeriek.
X
X
X
400
G073
‘chauffeur.rijbewijs.land’ ontbreekt.
Verplicht veld
X
X
X
400
G074
Waarde van ‘chauffeur.rijbewijs.land’ voldoet niet aan de opmaak.
landcode conform ISO3166-1 alpha-2
X
X
X
400
G080
‘authenticatie’ ontbreekt.
verplicht bij I als gebeurteniscode = M100
X
X
400
G081
‘authenticatie.middel’ ontbreekt.
verplicht bij I als gebeurteniscode = M100
X
X
400
G082
Waarde van 'authenticatie.middel' voldoet niet aan de opmaak.
Zie paragraaf 3.3 voor toegestane waarden
X
X
400
G083
‘authenticatie.kenmerk’ ontbreekt.
verplicht bij I als gebeurteniscode = M100
X
X
400
G084
Waarde van ‘authenticatie.kenmerk’ voldoet niet aan de opmaak.
Veld is maximaal 32 alfanumeriek.
X
X
400
G090
‘ondernemer’ ontbreekt.
Verplicht
X
X
X
400
G091
‘ondernemer.kiwaNummer’ ontbreekt.
Verplicht
X
X
X
400
G092
Waarde van ‘ondernemer.kiwaNummer’ voldoet niet aan de opmaak.
Eerste positie is altijd een 'P', overige 6 posities zijn cijfers, wanneer de cijferreeks korter is dan 6 posities dient deze uitgevuld te zijn met voorloop- nullen (0).
X
X
X
400
G093
‘ondernemer.kvkNummer’ ontbreekt.
verplicht veld.
X
X
X
400
G094
Waarde van ‘ondernemer.kvkNummer’ voldoet niet aan de opmaak.
Wanneer de cijferreeks korter is dan 8 dan dient deze uitgevuld te zijn met voorloopnullen (0).
X
X
X
400
G100
‘voertuig’ ontbreekt.
Verplicht
X
400
G101
‘voertuig.kenteken’ ontbreekt.
Verplicht
X
400
G103
Waarde van 'voertuig.kenteken' voldoet niet aan de opmaak.
Regex ^[0-9A-Z]{6}$
X
400
G104
‘voertuig.validatiemethode’ ontbreekt.
Verplicht
X
400
G105
Waarde van ‘voertuig.validatiemethode’ voldoet niet aan de opmaak.
enumeratie
X
400
G106
‘voertuig.validatiedatum’ ontbreekt.
Verplicht
X
400
G107
Waarde van ‘voertuig.validatiedatum’ voldoet niet aan de opmaak.
YYYY-MM-DD
X
400
G108
Waarde van ‘voertuig.validatiedatum’ is in de toekomst.
De validatiedatum kan niet in de toekomst liggen
X
400
G110
‘andereWerkzaamheden.begintijdstip’ ontbreekt.
Verplicht als andereWerkzaamheden aanwezig is
X
400
G111
Waarde van 'andereWerkzaamheden.begintijdstip' voldoet niet aan de opmaak.
De datum/tijd is in UTC, ISO-format yyyy-MM-ddThh:mm:ss.sssZ
X
400
G120
‘andereWerkzaamheden.eindetijdstip’ ontbreekt.
Verplicht als andereWerkzaamheden aanwezig is
X
400
G121
Waarde van ‘andereWerkzaamheden.eindetijdstip’ voldoet niet aan de opmaak.
De datum/tijd is in UTC, ISO-format yyyy-MM-ddThh:mm:ss.sssZ
X
400
G122
‘andereWerkzaamheden.eindetijdstip’ is voor ‘andereWerkzaamheden.starttijdstip’.
Start moet voor einde liggen
X
400
G123
Waarde van ‘andereWerkzaamheden.eindetijdstip’ is na ‘dienst.aanmeldtijdstip’.
Einde andere werkzaamheden moet voor aanmeldtijdstip dienst liggen
X
400
G130
‘locatie’ ontbreekt.
verplicht object bij:
- aanmelden rit (C)
- gebeurteniscode M102 en M103
X
X
400
G131
‘locatie.breedtegraad’ ontbreekt.
verplicht op locatie
X
X
400
G132
Waarde van ‘locatie.breedtegraad’ voldoet niet aan de opmaak.
Numeric(8,6)
X
X
400
G133
‘locatie.lengtegraad’ ontbreekt.
verplicht op locatie
X
X
400
G134
Waarde van ‘locatie.lengtegraad’ voldoet niet aan de opmaak.
Numeric(9,6)
X
X
400
G140
‘afstand’ ontbreekt.
verplicht bij afmelden rit
X
400
G141
Waarde van ‘afstand’ voldoet niet aan de opmaak.
Numeric
X
400
G150
‘ritprijs’ ontbreekt.
verplicht bij rit
X
400
G151
Waarde van ‘ritprijs’ voldoet niet aan de opmaak.
Integer
X
400
G160
Waarde van padparameter ‘rit’ voldoet niet aan de opmaak.
UUID
X
400
G170
Waarde van padparameter ‘pauze’ voldoet niet aan de opmaak.
UUID
X
400
G180
‘gebeurtenistijdstip’ ontbreekt.
Verplicht op melden gebeurtenis
X
400
G181
Waarde van ‘gebeurtenistijdstip’ voldoet niet aan de opmaak.
De datum/tijd is in UTC, ISO-format yyyy-MM-ddThh:mm:ss.sssZ
X
400
G182
Waarde van ‘gebeurtenistijdstip’ is in de toekomst.
Gebeurtenissen kunnen niet voor het gebeurtenistijdstip worden gemeld.
X
400
G190
‘gebeurteniscode’ ontbreekt.
verplicht veld
X
400
G191
Waarde van ‘gebeurteniscode’ voldoet niet aan de opmaak.
String(4)
X
3.16.3
Foutmeldingen wegens verwerken inhoud
400
DF01
Waarde van ‘aanmeldtijdstip’ is binnen een andere dienst.
Een dienst kan alleen aangemeld worden wanneer de begintijd van de dienst niet overlapt met een afgemelde dienst voor dezelfde chauffeur.
X
400
DF02
Waarde van ‘id’ is niet uniek.
Identificatie moet uniek zijn
X
X
X
X
400
DF03
Dienst kan niet worden gevonden op basis van het opgegeven id.
Een melding binnen een dienst kan alleen worden gedaan wanneer de dienst gevonden kan worden.
X
X
X
X
X
X
400
DF04
Dienst is reeds afgemeld.
Een dienst kan alleen afgemeld worden wanneer de dienst niet reeds afgemeld is.
X
400
DF051
Er zijn niet-afgemelde verrichtingen op deze dienst.
Een dienst kan worden afgemeld als alle verrichtingen op die dienst zijn afgemeld.
X
400
DF09
Waarde van ‘afmeldtijdstip’ ligt voor ‘aanmeldtijdstip’ van de dienst
Een dienst kan niet worden afgemeld voor een tijdstip dat ligt voor het aanmeldtijdstip
X
400
DF10
Waarde van ‘afmeldtijdstip’ ligt voor ‘afmeldtijdstip’ van verrichtingen in de dienst
Een afmeldtijdstip van een dienst kan niet liggen voor aan- of afmeldtijdstippen van verrichtingen binnen de dienst.
X
400
DF11
Waarde van ‘afmeldtijdstip’ valt binnen een andere dienst
Deze kan alleen voorkomen bij achteraf aangeleverde diensten.
X
400
VF01
Waarde van ‘aanmeldtijdstip’ is voor 'dienst.aanmeldtijdstip'.
Verrichting binnen dienst kan niet eerder beginnen dan dienst
X
X
400
VF02
Verrichting kan niet worden gevonden op basis van het opgegeven id.
Een verrichting (rit/pauze) kan alleen worden afgemeld wanneer deze is aangemeld.
X
X
400
VF03
Verrichting is reeds afgemeld.
Een afgemelde verrichting (rit/pauze) kan niet worden afgemeld.
X
X
400
VF04
Waarde van ‘afmeldtijdstip’ is voor ‘aanmeldtijdstip’ van verrichting.
Een verrichting binnen een dienst kan niet eindigen voor het begin van de verrichting
X
X
400
VF05
Het maximale aantal verrichtingen is bereikt voor deze dienst.
Het aantal verrichtingen per dienst is gemaximaliseerd op 100.
X
X
400
VF06
Waarde van ‘aanmeldtijdstip’ van pauze is binnen rit of pauze.
Een pauze mag niet overlappen met een andere verrichting.
X
400
VF07
Waarde van ‘aanmeldtijdstip’ van rit is binnen gemelde pauze.
Een rit kan niet worden gestart als:
• eerder een pauze is aangemeld en niet afgemeld;
• het aanmeldtijdstip valt binnen een aan- en afgemelde pauze.
X
400
VF08
Waarde van ‘afmeldtijdstip’ van pauze is binnen rit of pauze.
Een pauze mag niet overlappen met een andere verrichting. NB: deze fout kan in principe alleen voorkomen als achteraf een pauze wordt gemeld.
X
400
VF09
Waarde van ‘afmeldtijdstip’ van rit niet toegestaan, pauze tijdens rit.
Een rit kan niet worden afgemeld als daardoor een pauze tijdens de rit komt te vallen.
X
400
VF10
Verrichting niet gevonden binnen de opgegeven dienst
Er wordt een rit of pauze afgemeld waarvan de ID niet bekend is op de dienst
X
X
400
VF11
Waarde van ‘aanmeldtijdstip’ van pauze is voor aangemelde verrichting
Het is niet toegestaan een pauze te melden met een aanmeldtijdstip voor het aanmeldtijdstip van een andere verrichting.
X
400
BF01
Het maximale aantal gebeurtenissen is bereikt voor deze dienst.
Het aantal gebeurtenissen per dienst is gemaximaliseerd op 100.
X
X
400
OF01
Maximum aantal opvragingen bereikt
Er geldt een maximaal aantal opvragingen van 500 per dag per ICT-dienstverlener
X
1 Bij deze code wordt ook de betreffende verrichting(en) teruggegeven in de response.
4
Technische eisen
4.1
Conventies
4.1.1
JSON conventies
De Centrale applicatie dient de berichten aan te bieden aan de endpoints van CDT-Meldingen-API door middel van JSON (JavaScript Object Notation) berichten en REST (Representational State Transfer).
Voor een complete technische specificatie van de JSON berichten kan de OpenAPI-specificatie geraadpleegd worden, dit is REF-1.
Velden die geen waarde hebben worden weggelaten.
4.1.2
Encoding
De character-encoding standaard van de berichten is UTF-8.
4.1.3
Hoofdlettergevoeligheid
De backend service CDT is WEL hoofdlettergevoelig.
4.1.4
Datum/tijd
Voor datum en tijd wordt IETF RFC 3339 standaard gehanteerd, specifiek de specificatie van de ‘date-time’ waarde. Alle tijdstippen zijn in UTC.
4.1.5
Berichtenverkeer
Het berichtenverkeer wordt synchroon afgehandeld. Indien er sprake is van een time-out dient de Centrale applicatie het bericht opnieuw aan te bieden. Een transactie is pas afgerond als een response is ontvangen.
De aanroeper van een transactie dient minimaal 15 seconden te wachten voordat de transactie als timed-out mag worden beschouwd.
4.1.6
Endpoints
Alle endpoints zijn gespecifieerd in de OpenAPI specificatie [REF-1].
4.2
Actualiteit van data
Berichten dienen zonder vertraging aangeleverd te worden aan de backend service CDT. Elk bericht bevat twee tijdstempels: het moment waarop het feit heeft plaatsgevonden (aanmeldtijdstip of afmeldtijdstip) en het moment waarop het bericht over deze actie wordt aangemaakt (registratietijdstip). In de header ‘verzendtijdstip’ staat het tijdstip waarop de centrale applicatie de aanroep naar de CDT Meldingen API doet.
De ICT-dienstverlener is ervoor verantwoordelijk dat berichten op chronologische volgorde van registratietijdstip worden aangeleverd.
4.3
Beschikbaarheid en performance
4.3.1
Beschikbaarheid
De API heeft een gegarandeerde beschikbaarheid van 98%.
4.3.2
Performance
De streeftijd voor het afhandelen van een bericht is < 2 seconden.
5
Logging en monitoring verbinding
5.1
Logging
Voor beheerdoeleinden verwacht ILT dat de ICT-dienstverlener alle transacties op de CDT-Meldingen-API logt, inclusief de response van ILT. Deze gegevens dienen minimaal 1 maand te worden bewaard.
5.2
Connectie-monitoring
Om te monitoren of verbinding tussen de ICT-dienstverlener en ILT mogelijk is, stuurt de ICT-dienstverlener als er langer dan 60 seconden geen andere melding is gestuurd een GET naar https://[host]/v2/verbinding, waarop ILT een 200 OK zal terugsturen als teken dat de verbinding tot stand is gekomen. Op deze manier kunnen de beheerorganisaties van beide partijen monitoren of de connectie in orde is.
NB: indien de aanroep naar dit endpoint niet slaagt mogen andere transacties niet worden aangeroepen totdat deze aanroep weer slaagt.
6
Foutafhandeling
Het kan gebeuren dat er fouten optreden in één of meer berichten. Dit hoofdstuk beschrijft wat in welk geval moet gebeuren.
6.1
Algemeen
Als een bericht met betrekking op een dienst wordt afgewezen dienen berichten voor dezelfde dienst, die chronologisch na dat bericht moeten worden verstuurd, te worden vastgehouden totdat het afgewezen bericht (al dan niet gecorrigeerd) succesvol door de CDT-Meldingen-API is verwerkt.
Als het /verbinding-endpoint een 500-error geeft is er naar alle waarschijnlijkheid sprake van een verbindingsfout. Er dienen dan geen andere berichten verstuurd te worden naar de CDT Meldingen API en dient er in plaats hiervan iedere minuut een nieuwe oproep naar /verbinding gedaan te worden totdat deze oproep slaagt. Hierna kan het verzenden van de andere berichten weer hervat worden.
6.2
Error in aanroep dienstgerelateerde endpoints
Als in één van de aanroepen een foutsituatie optreedt dan worden acties aanbevolen zoals hieronder in de tabel beschreven.
403
Ongeautoriseerde oproep. Er zijn verkeerde credentials of een onbekend endpoint opgegeven. Herstel is noodzakelijk voor een nieuwe poging.
400
Bij een 400 wegens fouten in de header of het bericht: herstel eerst de fout en stuur dan een nieuw bericht met de herstelde gegevens.
50x
De CDT Meldingen API is niet bereikbaar. Probeer na 1 minuut opnieuw (zelfde message body, ander-tijdstip, zelfde berichtId).
6.3
Error in aanroep /verbinding
Het /verbinding endpoint wordt gebruikt om te controleren of de CDT Meldingen API operationeel is. Dit is een apart geval en is daarom apart behandeld. Als er andere berichten naar de CDT Meldingen API worden verstuurd dient het /verbinding endpoint niet aangeroepen te worden.
40x
Er is een fout gemaakt in de aanroep. Probeer opnieuw met een nieuw bericht.
50x
De CDT Meldingen API is niet bereikbaar. Probeer na 1 minuut opnieuw met een nieuwe aanroep van /verbinding, de huidige oproep mag niet opnieuw aangeboden worden (geen retry voor /verbinding)
6.4
Duplicaat detectie
Er is geen duplicaat-detectie, een bericht dat voor de tweede keer wordt aangeboden wordt functioneel afgewezen.
7
Authenticatie en informatiebeveiliging
7.1
Authenticatie
7.1.1
PKI Certificaten
De informatie-uitwisseling met de CDT meldingen-API verloopt via de centrale API Security gateway van de ILT waarop alle ICT-dienstverleners aangesloten dienen te worden. Authenticatie door de ICT-dienstverleners vindt plaats met behulp van PKI overheid servercertificaten en clientcertificaten bij de ICT-dienstverlener. Voor meer informatie zie de website van Logius.
7.1.2
Authenticatie rijbewijs
Bij iedere dienst die wordt gestart dient het Nederlandse rijbewijs van de chauffeur elektronisch te worden geauthenticeerd via NFC. Dit wordt gedaan door de ‘Active Authentication’ van het rijbewijs uit te voeren zoals beschreven in [REF-2]. Als dit met succes is uitgevoerd wordt op het aanmelden dienst-bericht het authenticatie-object gevuld met authenticatie.middel: ‘RBNL’ en authenticatie.kenmerk: het uitgelezen rijbewijsnummer. Als de chauffeur niet beschikt over een Nederlands rijbewijs dient op één van de overige wijzen geauthenticeerd te worden. Deze zijn beschreven in paragraaf 3.3.3.
NB: voor het uitlezen van de specimen rijbewijzen die beschikbaar zijn dient u gebruik te maken van aparte certificaten die niet op de website van de RDW beschikbaar zijn. Deze kunt u verkrijgen bij de aansluitcoördinatoren van de ILT.
7.1.3
Authenticatie kentekenbewijs
Bij het aanmelden van een voertuig voor een vervoerder dient het kentekenbewijs van het voertuig te worden geauthenticeerd middels de ‘Active Authentication’ zoals beschreven in [REF-3]. Hierbij wordt het kenteken van het voertuig uitgelezen middels een smartcard-lezer. Hierna mag het kenteken worden gebruikt voor diensten en ritten van deze vervoerder.
Het is mogelijk dat een voertuig door verschillende vervoerders wordt gebruikt, voor iedere vervoerder dient het kentekenbewijs éénmalig te worden geauthenticeerd voor het in gebruik nemen van het voertuig.
NB: voor het uitlezen van de specimen kentekenbewijzen die beschikbaar zijn dient u gebruik te maken van aparte certificaten die niet op de website van de RDW beschikbaar zijn. Deze kunt u verkrijgen bij de aansluitcoördinatoren van de ILT.
7.2
Informatiebeveiliging
De informatie-uitwisseling gaat van de aanleverende ICT-dienstverleners via het openbare internet naar de beveiligde API-gateway. Alleen vooraf vrijgegeven IP-adressen kunnen berichten hierop aanbieden. De gateway bevindt zich binnen de overheidsinfrastructuur.
7.2.1
Transport Layer Security (TLS)
Het verkeer vindt plaats over TLS met certificaten aan verzendende en ontvangende zijde. Hiervoor wordt gebruik gemaakt van de actuele standaarden zoals voorgeschreven door Forum Standaardisatie. De certificaten aan ontvangende zijde zijn van de Certificate Authority (CA) van de Rijksoverheid, de certificaten aan verzendende zijde moeten van een publieke CA zijn; de meeste CA's zijn bij de Rijksoverheid bekend en worden geaccepteerd. Mocht er twijfel zijn over een CA neemt u dan contact op de ILT. De meest actuele richtlijnen zijn door het NCSC beschreven in het document ICT-beveiligingsrichtlijnen voor Transport Layer Security (TLS) v2.1.
NB: de acceptatie-omgeving wijkt af van de productieomgeving: in de acceptatieomgeving is geen client-certificaat vereist.
7.2.2
API-keys
De ILT geeft per ICT-dienstverlener een API-key (ext_key-header) uit, de ICT-dienstverlener gebruikt de API-key om zich bij de ILT API-gateway te identificeren.
7.3
Headers
De CDT-Meldingen API verwacht de volgende headers:
