MAGDA Mobiliteit

Inleiding

Voertuiggegevens ophalen. Deze info kunnen gemeentes gebruiken voor het aanrekenen van parkeerretributies of GAS-boetes. Daarnaast zijn er ook use cases met betrekking tot lage emissie zones of voertuigkeuringen.

Use cases

• Automatisch de titularis van een nummerplaat achterhalen voor het aanrekenen van parkeerretributies of GAS-boetes (bijvoorbeeld na vaststelling door een sanctionerend ambtenaar, een scanwagen of een ANPR-camera).

• Nagaan of een voertuig toegang heeft tot een lage-emissiezone op basis van de voertuigkenmerken (brandstoftype, vermogen, euronorm), rekening houdend met het proportionaliteitsbeginsel binnen de GDPR.

• Bepalen van de ouderdom van een voertuig ter voorbereiding van een uitnodiging tot keuring (convocatie).

• Opzoeken van de titularis van een buitenlands voertuig, bijvoorbeeld bij een vastgestelde overtreding met een niet-Belgische nummerplaat.

• Actuele adresgegevens van de titularis ophalen (indien de instelling hiervoor een aparte machtiging heeft) voor correcte facturatie of aanmaning.

Setup

Idem als bij alle MAGDA-connectoren. Zie MAGDA algemene setup.

Specifieke applicatie eigenschappen

Specifieke applicatie eigenschappen, los van de eigenschappen die de toegang regelen.

Car

Enkel voor giveCar.

Mobility

Voor de overige functies.

Services en functies

Overzicht

giveCar

Vraag voertuiggegevens op op basis van nummerplaat.

Workflow expressie

${magda.giveCar(String licensePlate, String date, String dossierId)}

Java-code

GeefVoertuigResponse response = magda.giveCar(licensePlate, date, dossierId);

Input

MAGDA-documentatie

Technische documentatie rond geefVoertuig

Output

Je krijgt een getypeerd GeefVoertuigResponse-object terug met de gegevens van het voertuig: nummerplaat, chassisnummer, eigenaar (INSZ of ondernemingsnummer, nooit beide), commerciële naam, kleur, categorie, euronorm en datum van eerste inschrijving. Daarnaast bevat het object ook uitgebreidere technische gegevens (afmetingen, massa, vermogen, brandstof, ...) en gegevens over de status en levenscyclus van de inschrijving.

Gepseudonimiseerd voorbeeld:

<Inhoud>
    <Voertuig>
        <Nummerplaat>1AAA123</Nummerplaat>
        <Chassisnummer>2FTJW35GXRCA04699</Chassisnummer>
        <Eigenaar>
            <INSZ>850102XXX45</INSZ>
        </Eigenaar>
        <CommercieleNaam>OPEL CORSA</CommercieleNaam>
        <Kleur>
            <Code>J</Code>
            <Omschrijving>Oranje</Omschrijving>
        </Kleur>
        <Categorie>
            <Code>M1</Code>
            <Omschrijving>VOERTUIGEN BESTEMD VOOR PERSONENVERVOER - TEN HOOGSTE 8 ZITPLAATSEN, BESTUURDER NIET MEEGEREKEND</Omschrijving>
        </Categorie>
        <Euronorm>
            <Code>6</Code>
            <Omschrijving>Euro 6</Omschrijving>
        </Euronorm>
        <DatumEersteInschrijving>2015-05-06</DatumEersteInschrijving>
    </Voertuig>
</Inhoud>

(Opmerking: Eigenaar bevat óf een INSZ-element óf een Ondernemingsnummer-element, nooit beide — afhankelijk van of de eigenaar een natuurlijke persoon of een onderneming is.)

Error-handling

Aan deze functie gerelateerde foutcodes:

Voor een compleet overzicht, kan je terecht op de MAGDA-foutcodepagina.

Bij sommige errors wil je het proces niet laten vastlopen. In dat geval vorm je de technische error (foutcode) om naar een BPMN-error en vang je deze op via een error boundary event.

// Voorbeeld: uitzondering opvangen en gooien als BpmnError
GeefVoertuigResponse response = magda.giveCar(licensePlate, date, dossierId);

List<UitzonderingType> uitzonderingen = response.getRepliek()
    .getAntwoorden().getAntwoord().getUitzonderingen().getUitzondering();

for (UitzonderingType uitzondering : uitzonderingen) {
    String code = uitzondering.getIdentificatie();
    if ("30001".equals(code)) {
        throw new BpmnError("MAGDA_VOERTUIG_NIET_GEVONDEN", uitzondering.getDiagnose());
    }
    if ("40131".equals(code)) {
        throw new BpmnError("MAGDA_NUMMERPLAAT_ONBEKEND", uitzondering.getDiagnose());
    }
    if ("40005".equals(code)) {
        throw new BpmnError("MAGDA_TOEGANG_GEWEIGERD", uitzondering.getDiagnose());
    }
    if ("60009".equals(code)) {
        throw new BpmnError("MAGDA_TECHNISCHE_FOUT", uitzondering.getDiagnose());
    }
}

giveCrossbordertitularsByPlate

Vraag gegevens buitenlandse voertuigen op op basis van nummerplaat.

Workflow expressie 1

${magda.giveCrossbordertitularsByPlate(String plateNr1, String countryCode)}

Workflow expressie 2

${magda.giveCrossbordertitularsByPlate(String plateNr1, String countryCode, String dateTime)}

Java-code 1

CrossborderTitularsResponse response = magda.giveCrossbordertitularsByPlate(plateNr1, countryCode);

Java-code 2

CrossborderTitularsResponse response = magda.giveCrossbordertitularsByPlate(plateNr1, countryCode, dateTime);

Input

MAGDA-documentatie

Technische documentatie rond mobility/crossborderTitulars-v1

Output

Je krijgt een getypeerd CrossborderTitularsResponse-object terug (JSON-LD) met de titularisgegevens van het buitenlandse voertuig. Het antwoord bevat een items-lijst met licentie-objecten; elk licentie-object bevat de gegevens van de titularis — ofwel als natuurlijke persoon (person), ofwel als organisatie (organisation), nooit beide — samen met diens contactinformatie (adres) en de landcode van de registratiedocumenten.

Gepseudonimiseerd voorbeeld (JSON-LD, gebaseerd op de officiële elementbeschrijving):

{
  "@context": "https://vlaamseoverheid.be/oslo/mobility/context",
  "self": "https://api.magda.vlaanderen.be/mobility/crossborderTitulars/SE/ABC123",
  "items": [
    {
      "license": {
        "@id": "_:100",
        "@type": "License",
        "person": {
          "firstName": "Anna",
          "lastName": "Peeters"
        },
        "contactInfo": {
          "address": {
            "streetName": "Kerkstraat",
            "houseNumber": "12",
            "postalCode": "9000",
            "municipality": "Gent",
            "country": "BE"
          }
        },
        "registrationLanguageCode": "SE",
        "type": "person"
      }
    }
  ]
}

Error-handling

Deze functie spreekt een REST-dienst aan. Foutafhandeling verloopt hier niet via een Uitzonderingen-lijst in het antwoord (zoals bij de SOAP-diensten), maar via de HTTP-statuscode van de aanroep. Bij een fout gooit de onderliggende RestTemplate een HttpStatusCodeException.

// Voorbeeld: HTTP-fout opvangen en omzetten naar een BpmnError
try {
    CrossborderTitularsResponse response = magda.giveCrossbordertitularsByPlate(plateNr1, countryCode);
    // verwerk response
} catch (HttpClientErrorException.BadRequest e) {
    throw new BpmnError("MAGDA_ONGELDIGE_VRAAG", e.getMessage());
} catch (HttpClientErrorException.Unauthorized e) {
    throw new BpmnError("MAGDA_TOEGANG_GEWEIGERD", e.getMessage());
} catch (HttpServerErrorException e) {
    throw new BpmnError("MAGDA_TECHNISCHE_FOUT", e.getMessage());
}

giveRegistrationsTitularByPlate

Vraag voertuiggegevens op op basis van nummerplaat.

Workflow expressie

${magda.giveRegistrationsTitularByPlate(String plateNr, String date, String addressEnrichmentPerson, String addressEnrichmentOrganisation)}

Java-code

RegistrationsTitularResponse response = magda.giveRegistrationsTitularByPlate(plateNr, date, addressEnrichmentPerson, addressEnrichmentOrganisation);

Input

Alle parameters behalve plateNr zijn optioneel — geef null of een lege waarde mee indien niet van toepassing.

Magda-documentatie

Technische documentatie rond mobility/registrationsTitular-v1

Output

Je krijgt een getypeerd RegistrationsTitularResponse-object terug (JSON-LD) met een items-lijst van "registration"-objecten. Elk registration-object bevat vier deelobjecten: driver (de gewone bestuurder van het voertuig), license (gegevens rond de nummerplaat), titular (de titularis — een natuurlijke persoon of een onderneming, nooit beide) en vehicle (technische gegevens van het voertuig). Doorgaans komt er 0 of 1 registration terug; meerdere zijn ook toegestaan.

Gepseudonimiseerd voorbeeld:

{
  "@context": "https://vlaamseoverheid.be/oslo/mobility/context",
  "self": "https://api.magda.vlaanderen.be/mobility/registrationsTitular?plateNr=1ABC123",
  "items": [
    {
      "registration": {
        "driver": {
          "firstName": "Anna",
          "lastName": "Peeters"
        },
        "license": {
          "plateNumber": "1ABC123",
          "firstRegistrationDate": "2015-05-06"
        },
        "titular": {
          "person": {
            "nationalNr": "850102XXX45",
            "firstName": "Anna",
            "lastName": "Peeters"
          },
          "contactInfo": {
            "address": {
              "streetName": "Kerkstraat",
              "houseNumber": "12",
              "postalCode": "9000",
              "municipality": "Gent",
              "country": "BE"
            }
          }
        },
        "vehicle": {
          "chassisNumber": "2FTJW35GXRCA04699",
          "commercialName": "OPEL CORSA",
          "colour": "Oranje"
        }
      }
    }
  ]
}

Error-handling

Deze functie spreekt een REST-dienst aan. Foutafhandeling verloopt hier niet via een Uitzonderingen-lijst in het antwoord (zoals bij de SOAP-diensten), maar via de HTTP-statuscode van de aanroep. Bij een fout gooit de onderliggende RestTemplate een HttpStatusCodeException.

Bij sommige fouten wil je het proces niet laten vastlopen. In dat geval vorm je de HTTP-fout om naar een BPMN-error en vang je deze vervolgens op via een error boundary event.

try {
    RegistrationsTitularResponse response = magda.giveRegistrationsTitularByPlate(plateNr, date, addressEnrichmentPerson, addressEnrichmentOrganisation);
    // verwerk response
} catch (HttpClientErrorException.BadRequest e) {
    throw new BpmnError("MAGDA_ONGELDIGE_VRAAG", e.getMessage());
} catch (HttpClientErrorException.Unauthorized e) {
    throw new BpmnError("MAGDA_TOEGANG_GEWEIGERD", e.getMessage());
} catch (HttpServerErrorException e) {
    throw new BpmnError("MAGDA_TECHNISCHE_FOUT", e.getMessage());
}