Generieke interface energielabels

Handleiding Generieke interface energielabels In opdracht van het ministerie van Binnenlandse Zaken en Koninkrijksrelaties (Directie Woningbouw)

1 1.1 1.2 1.3

Inleiding—3 Doel—3 Korte omschrijving—3 Indeling document—4

2 2.1 2.2 2.3

Samenhang tussen de drie interface-vormen—5 Uitgangspunten:—5 Maatregelen om aan deze uitgangspunten tegemoet te komen:—5 Relatie tussen de bestanden met "Dagset mutaties" en "Volledige actuele set"—6

3 3.1 3.2 3.3 3.4 3.5

Interface Actuele Energielabels—7 Attributen Volledige Set—7 Attributen Dagmutatie Set—8 Naamgeving bestanden—8 Moment van genereren—9 FTP-Postbus (bestanden)—9

4 4.1 4.2 4.3 4.4

Webservice opvragen pandcertificaat—10 Verzoek—10 Antwoord—11 Toegang—12 WSDL—12 Colofon—13

Versie 1.0 – 6 juni 2013 – Auteur: H. Siers (Sogeti)

Handleiding generieke interface energielabels

Pagina 2 van 13

1

Inleiding

1.1

Doel

Deze handleiding is bedoeld voor de organisaties die gebruik willen maken van de interface die RVO.nl aanbiedt om de informatie over actuele energielabels van panden ter beschikking te stellen aan marktpartijen. De interface bestaat uit drie elementen: Periodiek bestand met een volledige set van alle actuele energielabels, ook wel pandcertificaten genoemd. Dagelijkse mutatiebestanden. Een webservice om in geval van twijfel het laatst geregistreerde Energielabel van een pand op te vragen. Van alle drie de vormen van aansluiten wordt in deze handleiding uitgelegd hoe die te realiseren.

1.2

Korte omschrijving

Naar aanleiding van de marktvraag omtrent informatie over energielabels zoals die verstrekt worden volgens de "Energy Performance Building Directive" heeft RVO.nl besloten om een generieke interface te laten realiseren waarbij de gegevens van de energielabels via een elektronische interface aan geautoriseerde afnemers ter beschikking wordt gesteld. Deze generieke interface is in staat om een selectie van gegevens die een 1:1 relatie hebben met een Energielabel (pandcertificaat) ter beschikking te stellen. Afnemers dienen in staat gesteld worden om technisch/infrastructureel en functioneel aan te sluiten op de interface en afnemers moeten voor realisatie van hun eigen aansluiting weten hoe de set van attributen verwerkt kan worden. Deze handleiding beschrijft deze aspecten van aansluiting op deze interface. Om gebruik te kunnen maken van de interfaces moet de afnemer geautoriseerd zijn. Een afnemer kan hiertoe een aanvraag indienen bij RVO.nl via het formulier ‘Gebruikersverklaring webservice EPBD-afmeldsysteem’. Nadat een afnemer geautoriseerd is zal deze beschikken over de volgende gegevens waar in dit document naar wordt verwezen via de volgende notatie en gekleurde tekst: <Webserver> <postbusnaam> <username> <password>


Pagina 3 van 13

1.3

Indeling document

Het document kent de volgende indeling: Hoofdstuk 3: beschrijving van de samenhang tussen de 3 interfaces. Hoofdstuk 4: beschrijving van de interfaces voor de actuele energielabels. Hoofdstuk 5: beschrijving van de “webservice opvragen pandcertificaat”.


Pagina 4 van 13

2

Samenhang tussen de drie interface-vormen

Vanwege eerdere ervaringen opgedaan met synchronisaties tussen databases die niet gebaseerd zijn op volledige synchronisatie, is besloten om het ontwerp te baseren op het herstellen van een inconsistente situatie door de afnemer zelf.

2.1

Uitgangspunten: De "actualiteit" van vorige dag is in 99,9 % van de gevallen voor de afnemers goed genoeg om de informatie als betrouwbaar te beschouwen. In geval van twijfel of discussie is er een mogelijkheid om voor één specifiek pand de meest actuele situatie op te vragen. Afnemers die constateren dat ze een inconsistente database hebben moeten ten alle tijde in staat zijn om die situatie te corrigeren.

2.2

Maatregelen om aan deze uitgangspunten tegemoet te komen: Iedere maand wordt aan alle afnemers een volledige set actuele energielabels ter beschikking gesteld. Iedere dag worden de mutaties van de vorige dag als "Dagset mutaties" ter beschikking gesteld zodat afnemers hun database kunnen bijwerken tot de situatie van "gisteren". Teneinde de mutaties in de juiste volgorde te kunnen verwerken, krijgt iedere mutatie een uniek mutatievolgnummer. Met de maandelijkse volledige set wordt het mutatievolgnummer van de laatst daarin verwerkte mutatie meegegeven. Om in geval van twijfel / discussie de werkelijke actuele stand voor een pand te kunnen vergelijken met die de afnemer in zijn eigen database heeft geregistreerd, is de interface "webservice opvragen pandcertificaat" gerealiseerd. Om overmatig gebruik van de interface "webservice opvragen pandcertificaat" te voorkomen wordt per afnemer het toegestane gebruik ingesteld.

Voor consequenties voor de afnemer zie Figuur 1: Mogelijkheden voor de afnemer voor database met "Volledig actuele set".


Pagina 5 van 13

Figuur 1: Mogelijkheden voor de afnemer voor database met "Volledig actuele set"

2.3

Relatie tussen de bestanden met "Dagset mutaties" en "Volledige actuele set"

De bestandsnamen van de "Volledig actuele set" en de "Dagset mutaties" lijken aan elkaar gerelateerd, maar zijn dat slechts ten dele. De "Dagset mutaties" bevat alle werkelijke mutaties die op de datum die in de bestandsnaam zit zijn uitgevoerd, de datum die in de bestandsnaam van de "Volledig actuele set" wordt vastgesteld op het startmoment van de verwerking (selectie op de database van RVO.nl). Bij gebruik van de "Volledig actuele set", dient vervolgens als eerste het bestand voor "Dagset mutaties" met dezelfde datum verwerkt te worden. Het eerste mutatievolgnummer daarin dat verwerkt moet worden is het mutatievolgnummer dat vermeld staat in de "Volledig actuele set" + 1. Dit is niet per definitie de eerste mutatie in het "Dagset mutaties"-bestand. Mutaties zitten wel opeenvolgend (op mutatievolgnummer) in het bestand. De werkelijke relatie tussen de "Dagset mutaties" en "Volledige actuele set" is bepaald met het mutatievolgnummer.


Pagina 6 van 13

3

Interface Actuele Energielabels

RVO.nl biedt een volledige set, en een dagmutatie set. Beide sets kennen voor wat betreft het pandcertificaat dezelfde attributen, en ze worden in de volgende paragrafen beschreven.

3.1

Attributen Volledige Set

De xsd van de Volledige set is gegeven in het bestand EpbdActueleSet.xsd, waarbij de types zijn gegeven in EpbdOpvragenPandEnergieLabelTypes.xsd. In onderstaande tabel een opsomming van en eventuele toelichting op de elementen. Element

Toelichting

VolledigeActueleSet LaatsteVerwerkteMutatieVolgnummer

Laatste mutatievolgnummer dat verwerkt is in deze set

Pandcertificaat

1 of meer binnen VolledigeActueleSet

PandVanMeting_postcode PandVanMeting_huisnummer PandVanMeting_huisnummer_toev PandVanMeting_gebouwcode PandVanMeting_opnamedatum PandVanMeting_berekeningstype PandVanMeting_energieprestatieindex PandVanMeting_energieklasse Meting_geldig_tot Pand_registratiedatum Pand_postcode Pand_huisnummer Pand_huisnummer_toev Pand_gebouwcode Pand_cert_type

“W” = Woningbouw, “U“ = Utiliteitsbouw

Pand_gebouwtype Pand_gebouwsubtype Pand_SBIcode Voor zover hier niet aangegeven, zijn de definities en mogelijke waarden van de attributen gegeven in de xsd.


Pagina 7 van 13

3.2

Attributen Dagmutatie Set

De xsd van de Dagmutatie set is gegeven in het bestand EpbdDagmutaties.xsd, waarbij de types zijn gegeven in EpbdOpvragenPandEnergieLabelTypes.xcs. In onderstaande tabel een opsomming van en eventuele toelichting op de elementen. Element

Toelichting

DagMutatieSet Mutatiedatum Mutatiebericht

1 of meer binnen DagMutatieSet

Mutatievolgnummer Stuurcode

1 = Toevoegen Energielabel, 2 = Verwijderen Energielabel.

Pandcertificaat

1 binnen Mutatiebericht

PandVanMeting_postcode PandVanMeting_huisnummer PandVanMeting_huisnummer_toev PandVanMeting_gebouwcode PandVanMeting_opnamedatum PandVanMeting_berekeningstype PandVanMeting_energieprestatieindex PandVanMeting_energieklasse Meting_geldig_tot Pand_registratiedatum Pand_postcode Pand_huisnummer Pand_huisnummer_toev Pand_gebouwcode Pand_cert_type


Pand_gebouwtype Pand_gebouwsubtype Pand_SBIcode Voor zover hier niet aangegeven, zijn de definities en mogelijke waarden van de attributen gegeven in de xsd.

3.3

Naamgeving bestanden

De bestanden kennen de volgende naamgevingsconventie; "Dagset mutaties" beginnen met een "d", "Volledige actuele set" beginnen met een "v". Onderstaand de logica van de naamgeving:


Pagina 8 van 13

dyyyymmdd.zip voor de "Dagset mutaties", dit is een gecomprimeerd bestand waarin het bestand dyyyymmdd.dx zit. Dit is een xml bestand. "Dagset mutaties". vyyyymmdd.zip voor de "Volledige actuele set", dit is een gecomprimeerd bestand waarin het bestand vyyyymmdd.dx zit. Dit is een xml bestand. Vanwege de enorme omvang (geschat maximaal 12 GB) is voor de extensie dx gekozen en niet de extensie xml. Zo wordt voorkomen dat het bestand bij aanklikken automatisch geopend zou worden. Het gecomprimeerde bestand is met een programma als winzip uit te pakken.

3.4

Moment van genereren

De volledige set wordt één keer per maand gecreëerd, in principe is dit aan het begin van de maand. De dagmutatieset wordt één keer per dag gecreëerd.

3.5

FTP-Postbus (bestanden)

De server waarop de bestanden met de postbus voor de "Dagset mutaties" en de "Volledige actuele set" staan kan bereikt worden met <postbusnaam> waarbij de <postbusnaam> specifiek is voor u als afnemer. Deze dient u dan ook opgegeven te krijgen van RVO.nl. Gebruikersnaam en wachtwoord waarmee u toegang krijgt tot uw eigen postbus dient u ook van RVO.nl te ontvangen. Slechts met uw account-informatie kunt u de inhoud van uw postbus zien (en ophalen). De bestanden die hier staan kunt u ophalen. Verwijdering van bestanden zal automatisch plaatsvinden In deze postbus zal normaal gesproken één periodieke set en ongeveer 30 dagsets staan. Met de aanwezige combinatie bent u altijd in staat om uw database compleet opnieuw op te bouwen en bij te werken tot de dag van gisteren.


Pagina 9 van 13

4

Webservice opvragen pandcertificaat

Dit hoofdstuk beschrijft de aansluiting op de webservice waarmee voor één specifiek pand de gegevens van het actuele Energielabel kan worden opgevraagd. Deze service is slechts bedoeld om in geval van twijfel (er wordt bijv. beweerd dat de weergave niet klopt) de gegevens direct bij RVO.nl op te vragen. De operaties bestaan uit: Verzoek Antwoord Deze worden in de volgende paragrafen uitgelegd.

4.1

Verzoek

Het verzoek bestaat uit twee delen: Header Request De header bevat de volgende elementen: Element

Toelichting

PandEnergieLabelHeader Username

<username>, Verplicht

Password

<password>, Verplicht

Versienr

= 3.1

Voor zover hier niet aangegeven, zijn de definities en mogelijke waarden van de attributen gegeven in de xsd. De request bevat de volgende elementen: Element

Toelichting

GetPandEnergieLabel Pand_postcode

Verplicht

Pand_huisnummer

Verplicht

Pand_huisnummer_toev

Niet verplicht

Pand_gebouwcode

Niet verplicht (dit veld is een toevoeging aan het adres als postcode, huisnummer en toevoeging het pand niet voldoende identificeren)

Voor zover hier niet aangegeven, zijn de definities en mogelijke waarden van de attributen gegeven in de xsd.


Pagina 10 van 13

4.2

Antwoord

Onder de volgende voorwaarden zal de webservice een antwoordbericht opstellen: 1. Het verzoek was correct opgesteld. 2. Het versienummer is goed. 3. De afnemer is geautoriseerd. Het antwoordbericht bevat de volgende elementen: Element

Toelichting

PandEnergieLabel

Kan 0 of 1 keer voorkomen. Komt voor als er een pandcertificaat wordt gevonden op exact het opgegeven adres. Komt niet voor als er geen pandcertificaat wordt gevonden op exact het opgegeven adres.

PandVanMeting_postcode PandVanMeting_huisnummer PandVanMeting_huisnummer_toev PandVanMeting_gebouwcode PandvanMeting_opnamedatum PandVanMeting_berekeningstype PandVanMeting_energieprestatieindex PandVanMeting_energieklasse Meting_geldig_tot Pand_registratiedatum Pand_postcode Pand_huisnummer Pand_huisnummer_toev Pand_gebouwcode Pand_cert_type


Pand_gebouwtype Pand_gebouwsubtype Pand_SBIcode Voor zover hier niet aangegeven, zijn de definities en mogelijke waarden van de attributen gegeven in de xsd. In alle andere gevallen zal één van de volgende 2 meldingen worden teruggegeven: ‘Technische storing, foutcode <programmamelding>` ‘Service tijdelijk niet beschikbaar`.


Pagina 11 van 13

4.3

Toegang

Het adres van deze webservice is <Webserver>EpbdOpvragenPandEnergieLabelService.asmx Gebruikersnaam en wachtwoord waarmee u toegang krijgt tot deze webservice dient u van RVO.nl te ontvangen.

4.4

WSDL

De definities van de berichten zijn gegeven in de volgende bestanden: EpbdOpvragenPandEnergieLabel.wsdl EpbdOpvragenPandEnergieLabelHeader.xsd EpbdOpvragenPandEnergieLabelRequest.xsd EpbdOpvragenPandEnergieLabelResponse.xsd EpbdOpvragenPandEnergieLabelTypes.xsd


Pagina 12 van 13

Colofon

Dit is een publicatie van: Rijksdienst voor Ondernemend Nederland Croeselaan 15 | 3521 BJ Utrecht Postbus 8242 | 3503 RE Utrecht T +31 (0) 88 042 42 42 F +31 (0) 88 602 90 23 E [email protected] www.rvo.nl Deze publicatie is tot stand gekomen in opdracht van het ministerie van Binnenlandse Zaken en Koninkrijksrelaties (Directie Woningbouw) © Rijksdienst voor Ondernemend Nederland | oktober 2014 Publicatienummer: RVO-027-1401/BR-DUZA De Rijksdienst voor Ondernemend Nederland (RVO.nl) stimuleert ondernemers bij duurzaam, agrarisch, innovatief en internationaal ondernemen. Met subsidies, het vinden van zakenpartners, kennis en het voldoen aan weten regelgeving. RVO.nl werkt in opdracht van ministeries en de Europese Unie. RVO.nl is een onderdeel van met ministerie van Economische Zaken. De opdrachtgever is verantwoordelijk voor de inhoud, Economische Zaken is verantwoordelijk voor de organisatie.


Pagina 13 van 13

Generieke interface energielabels

Recommend Documents