API Kabel- en Leidingbeheerders

Het KLIP Web API is een REST API, beveiligd door het OAuth 2.0 protocol.

Technische documentatie vindt u in de Swagger-documentatie.

In het algemeen is de relatie tussen een planaanvraag en een leidingbeheerder als volgt:

• Een organisatie is standaard geen leidingbeheerder: moet eerst ingesteld worden als leidingbeheerder

  • Het is perfect mogelijk om binnen een organisatie te werken met suborganisaties, die elk afzonderlijk ingeregeld kunnen worden als leidingbeheerder

  • Een KLB hangt aan een specifieke (sub)organisatie, er is een 1-1 relatie tussen de UnaId (integer) en de ID van de (sub)organisatie (GUID).

• Een KLB-zone is gekoppeld aan een leidingbeheerder (Una)

• Planaanvragen worden gekoppeld aan een KLB-zone (UnaZone)

(Sub)organisatie instellen als Kabel- en leidingbeheerder

Voordat een (sub)organisatie kan optreden als leidingbeheerder, moet deze zich eerst kenbaar maken als leidingbeheerder. In de webtoepassing doe je dit door onder de tekst met onder andere de antwoordtermijnen en verplichte antwoordmethode te bevestigen dat je leidingen beheert. Je kiest hier dan meteen ook een naam voor de leidingbeheerder in KLIP. Standaard is deze naam gelijk aan de naam van de (sub)organisatie, maar deze kan aangepast worden.

Via de API kan je

• alle KLB-zones van een specifieke (sub)organisatie opvragen

  • gebruik de organisations-calls om de ID’s van de verschillende suborganisaties op te vragen.

• voor een (sub)organisatie de gegevens van de desbetreffende leidingbeheerder opvragen:

  • naam

  • onderwerp signing certificaat

  • aan de leidingbeheerder gekoppelde KLB-zones

• de naam van de leidingbeheerder instellen (DisplayName)

• het onderwerp van het signing certificaat instellen (indien leidingbeheerder zijn IMKL-antwoorden digitaal ondertekent)

Na de productierelease is de documentatie beschikbaar op https://klip.api.vlaanderen.be/api/swagger/index.html#/Una.

Beheren van KLB-zones

Er zijn 2 soorten KLB-zones:

1. KLIM-KLB-zones

   1. hebben betrekking op transportleidingen voor olie, gas, chemicaliën of elektriciteit

   2. ligging van deze zones wordt beheerd in het KLIM-portaal

2. KLIP-KLB-zones

   1. zones die betrekking hebben op alle andere ondergrondse kabels en leidingen

   2. ligging wordt beheerd in KLIP

Via de API kan je

• alle zones van een bepaalde (sub)organisatie opvragen

• een nieuwe KLIP-KLB-zone toevoegen aan een leidingbeheerder

  • op basis van de OrganisationId van de leidingbeheerder

• een nieuwe KLIM-KLB-zone toevoegen aan een leidingbeheerder

  • op basis van de OrganisationId van de leidingbeheerder

  • Opgelet: de ID van nieuwe KLIM-KLB-zones in KLIP moeten in KLIM gekoppeld worden aan de overeenkomstige zone in KLIM.

• details van een KLB-zone opvragen:

  • contactgegevens

  • namespace

  • mailsettings

  • actieve geometrie (GeoJson of GML)

  • eventuele geplande geometrieën met hun activeringsdatum (GeoJson of GML)

  • aanduiding KLIP of KLIM-zone

• bestaande KLB-zones aanpassen

Na de productierelease is de documentatie beschikbaar op https://klip.api.vlaanderen.be/api/swagger/index.html#/UnaZone .

Antwoordproces

Een planaanvraag kan pas beantwoord worden wanneer ze de status ‘confirmed’ heeft.  

Aangewezen antwoordproces: 

1. Vraag de voor de bewuste KLB-zone te bevestigen planaanvragen op 

2. Bevestig planaanvragen 

3. Vraag de voor de bewuste KLB-zone te beantwoorden planaanvragen op 

4. Vraag de details te beantwoorden planaanvragen op 

5. Beantwoord de planaanvragen voor de bewuste KLB-zone

Alternatief antwoordproces: 

1. Vraag de voor de bewuste KLB-zone te bevestigen planaanvragen op

2. Bevestig planaanvraag 

3. Kijk na of de status van de planaanvraag aangepast is naar ‘confirmed’ voor de bewuste KLB-zone

4. Vraag details planaanvraag op 

5. Beantwoord de planaanvraag

Correct bevestigen en beantwoorden voor organisaties met meerdere suborganisaties en/of zones

Sinds de overstap naar het Toegangsbeheer Vlaanderen hebben gebruikers (ook oAuth-clients) toegang tot de volledige organisatiestructuur onder een hoofdorganisatie. Op het vlak van toegangsrechten is er GEEN onderscheid meer op basis van suborganisaties.

Je kan dus planaanvragen beantwoorden (not involved) die eigenlijk door andere partij beantwoord moeten worden

• Antwoorden met IMKL worden geweigerd als namsespace in antwoord niet correct is

• OrganisationId & UnaZoneId kunnen zowel via de API, maar ook in de de KLIP frontend opgezocht worden

Clients die de planafhandeling doen voor 1 bepaalde leidingbeheerder of KLB-zone, houden hier best rekening mee. Door het antwoordproces goed in te regelen kan je vermijden dat je planaanvragen behandeld die binnen een organisatie aan een andere KLB-zone hangen dan degene waarvoor de client verondersteld wordt om de afhandeling te doen.

Best practice:

1. Sla de ID’s van de KLB-zones op waarvoor de client in kwestie de planafhandeling doet

   1. ga er niet van uit dat je zomaar mag antwoorden op alle planaanvragen die een organisatie aankrijgt, sommige KLB-zones kunnen afgehandeld worden door een andere partij

2. Bevestig en beantwoord enkel die planaanvragen gekoppeld aan de KLB-zones die je effectief beheert