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

Via de API kan je

• alle KLB-zones van een (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

  • was deze (sub)organisatie nog niet gekend als leidingbeheerder, dan wordt op dit moment ook de bijhorende leidingbeheerder aangemaakt

• 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.

  • was deze (sub)organisatie nog niet gekend als leidingbeheerder, dan wordt op dit moment ook de bijhorende leidingbeheerder aangemaakt

• 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

Certificaten gebruikt voor ondertekening validatierapporten IMKL-antwoorden

De VODCB-certificaten die KLIP gebruikt om IMKL-validatierapporten digitaal te ondertekenen, hebben de volgende CN:

• KLIP Bèta: CN=signing.klip.vlaanderen.be/beta

• KLIP Productie: CN=signing.klip.vlaanderen.be/prod

Op 12/02/2025 werden de gebruikte certificaten vernieuwd. Wat betekent dat?

• KLIP Bèta

  • De CN=signing.klip.vlaanderen.be/beta blijft hetzelfde

  • De chain van het certificaat (die bestaat uit een intermediate en root VODCB-certificaat) verandert. Namelijk het internediate certificaat wordt vervangen door een nieuw.

•  KLIP Productie

  • De CN=signing.klip.vlaanderen.be/prod blijft hetzelfde

  • De chain van het certificaat (die bestaat uit een tussenliggend en root VODCB-certificaat) verandert. Namelijk het intermediate  certificaat wordt vervangen door een nieuw.

De nieuwste VODCB-intermediate en root-certificaat kunnen worden gedownload op DCBaaS Documenten. Het is het beste om alle 3 te installeren.

Toekomstige wijziging aan certificaten

Vanaf 1/1/2026 zal KLIP een ander CN gebruiken voor het ondertekenen van de validatierapporten:

• KLIP Bèta

  • De CN=signing.klip.vlaanderen.be/beta verandert in CN=signing.klip.athumi.eu/beta

  • Als u met CN-validatie werkt, moet de nieuwe CN=signing.klip.athumi.eu/beta vóór 01/01/2026 op de whitelist worden gezet

• KLIP Productie

  • De CN=signing.klip.vlaanderen.be/prod verandert in CN=signing.klip.athumi.eu/prod

  • Als u met CN-validatie werkt, moet de nieuwe CN=signing.klip.athumi.eu/prod vóór 01/01/2026 op de whitelist staan

   De oude CN blijft in gebruik tot 01/01/2026 en dan worden zowel de oude als de nieuwe CN geldig.

   Dus na 01/01/2026 moeten zowel de oude als de nieuwe CN op de whitelist staan.