Handleiding. Generieke interface energielabels. Versie juni 2013 Auteur: H. Siers (Sogeti)

Transcriptie

1 Handleiding Generieke interface energielabels Versie juni 2013 Auteur: H. Siers (Sogeti)

2 1 Inleiding Doel Korte omschrijving Indeling document 4 2 Samenhang tussen de drie interface-vormen Uitgangspunten: Maatregelen om aan deze uitgangspunten tegemoet te komen: Relatie tussen de bestanden met "Dagset mutaties" en "Volledige actuele set" 6 3 Interface Actuele Energielabels Attributen Volledige Set Attributen Dagmutatie Set Naamgeving bestanden Moment van genereren FTP-Postbus (bestanden) 9 4 Webservice opvragen pandcertificaat Verzoek Antwoord Toegang WSDL 12 Colofon 13 Handleiding generieke interface energielabels Pagina 2 van 13

3 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> <FTP-SERVER-adres> <postbusnaam> <username> <password> Handleiding generieke interface energielabels Pagina 3 van 13

4 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. Handleiding generieke interface energielabels Pagina 4 van 13

5 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". Handleiding generieke interface energielabels Pagina 5 van 13

6 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. Handleiding generieke interface energielabels Pagina 6 van 13

7 3 Interface Actuele Energielabels RVO.nl biedt een volledige set, en een dagmutatieset. 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 Pandcertificaat Laatste mutatievolgnummer dat verwerkt is in deze set 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. Handleiding generieke interface energielabels Pagina 7 van 13

8 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 DagMutatieSet Mutatiedatum Mutatiebericht Mutatievolgnummer Stuurcode Pandcertificaat 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 Toelichting 1 of meer binnen DagMutatieSet 1 = Toevoegen Energielabel, 2 = Verwijderen Energielabel. 1 binnen Mutatiebericht W = Woningbouw, U = Utiliteitsbouw 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: Handleiding generieke interface energielabels Pagina 8 van 13

9 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 <FTP-SERVERadres><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. Handleiding generieke interface energielabels Pagina 9 van 13

10 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 PandEnergieLabelHeader Username Password Versienr = 3.1 Toelichting <username>, Verplicht <password>, Verplicht 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 GetPandEnergieLabel Pand_postcode Pand_huisnummer Pand_huisnummer_toev Pand_gebouwcode Toelichting Verplicht Verplicht Niet verplicht 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. Handleiding generieke interface energielabels Pagina 10 van 13

11 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 PandEnergieLabel 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 Toelichting 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. W = Woningbouw, U = Utiliteitsbouw 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`. Handleiding generieke interface energielabels Pagina 11 van 13

12 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 Handleiding generieke interface energielabels Pagina 12 van 13

13 Colofon Deze publicatie is in opdracht van het ministerie van Binnenlandse Zaken en Koninkrijksrelaties (Directie Woningbouw) opgesteld door: Rijksdienst voor Ondernemend Nederland Croeselaan 15 Postbus RE Utrecht T +31 (0) E info@rvo.nl Rijksdienst voor Ondernemend Nederland juni 2013 Handleiding generieke interface energielabels Pagina 13 van 13