Handleiding generieke webservice energielabels In opdracht van het ministerie van Binnenlandse zaken en Koninkrijksrelaties

Transcriptie

1 Handleiding generieke webservice energielabels In opdracht van het ministerie van Binnenlandse zaken en Koninkrijksrelaties >> Duurzaam, Agrarisch, Innovatief en Internationaal ondernemen

2 INDEX Inleiding 3 1 Afnemeraccount aanvragen 4 2 Koppelvlak opvragen bestanden 5 3 Inhoud van het totaalbestand 6 4 Inhoud van het mutatiebestand 7 5 Handmatig opvragen bestanden 8 6 Koppelvlak opvragen bestanden : opvragen download-url 9 7 Koppelvlak opvragen : direct raadplegen van het register 11 INDEX 2/11

3 Inleiding In dit document vindt u meer informatie over het gebruik van de generieke webservice energielabels. Via deze webservice kunt u energielabels opvragen die in de database EP-online geregistreerd staan. De webservice bevat het koppelvlak opvragen en het koppelvlak opvragen bestanden. Met behulp van het koppelvlak opvragen kan een gebruiker de website EP-online.nl voor een enkele situatie bevragen. Met behulp van het koppelvlak opvragen bestanden kan een gebruiker een volledige dataset en aanvullende mutatiebestanden ophalen van de website. Hiermee kan de gebruiker een actueel bestand opbouwen van alle gebouwen in Nederland en hun energielabel en EI-waarde. De uitvoering van het Werkprogramma Energie & Gebouwde omgeving heeft ook in 2016 tot doel om het ministerie van Binnenlandse Zaken en Koninkrijksrelaties (BZK) te faciliteren bij het realiseren van het beleid op gebied van energiebesparing in en rond gebouwen. In dat kader verzorgt de Rijksdienst voor Ondernemend Nederland (RVO.nl) de implementatie van het energielabel. INDEX 3/11

4 1. Afnemeraccount aanvragen Om gebruik te kunnen maken van de webservice dient de gebruiker een afnemeraccount aan te vragen. Deze vraagt u aan door een ondertekende gebruikersverklaring op te sturen naar RVO.nl. Op basis van deze gebruikersverklaring wordt een account aangemaakt op de website EP-online.nl. Als u reeds een account in EP-online heeft, dan kunnen de rechten van dit account uitgebreid worden voor gebruik van de webservices opvragen en opvragen bestanden. INDEX 4/11

5 2. Koppelvlak opvragen bestanden Het koppelvlak opvragen bestanden genereert maandelijks een totaalbestand en dagelijks mutatiebestanden die kunnen worden uitgelezen om een eigen, lokale schaduwkopie van de registratie op te bouwen en te onderhouden. Het maandelijkse totaalbestand en de dagelijkse mutatiebestanden kunt u handmatig downloaden via EP-online.nl of via een tijdelijke download-url. Deze kunt u automatisch opvragen via de webservice. INDEX 5/11

6 3. Inhoud van het totaalbestand Het totaalbestand bevat een overzicht van de actuele situatie van geregistreerde energielabels en EI-certificaten in Nederland. In dit bestand staan van alle geregistreerde gebouwen, het meest recente energielabel of EI-certificaat. De structuur van het totaalbestand is xml. Het bestand bestaat uit een (lange) lijst met pandcertificaten. Elk totaalbestand heeft een extra gegeven: het laatst verwerkte mutatievolgnummer. De waarde van dit volgnummer moet overeenkomen met de waarde uit de laatst beschikbaar gestelde dagmutatie van de vorige maand. Wanneer dat niet zo is, moet worden aangenomen dat de lokale kopie van de registratie een of meerdere mutatieslagen heeft gemist en gedurende een periode niet actueel was. <?xml version="1.0" encoding="utf-8"?> <VolledigeActueleSet xmlns=" <LaatstVerwerkteMutatieVolgnummer xmlns=""> </laatstverwerktemutatievolgnummer> <Pandcertificaten xmlns=""> <Pandcertificaat> <PandVanMeting_postcode>1622KA</PandVanMeting_postcode> <PandVanMeting_huisnummer>1</PandVanMeting_huisnummer> <PandVanMeting_bagverblijfsobjectid> </PandVanMeting_bagverblijfsobjectid> <PandVanMeting_opnamedatum> </PandVanMeting_opnamedatum> <PandVanMeting_berekeningstype>EPA</PandVanMeting_berekeningstype> <PandVanMeting_energieprestatieindex>1.69</PandVanMeting_energieprestatieindex> <PandVanMeting_energieklasse>D</PandVanMeting_energieklasse> <PandVanMeting_gebouwklasse>W</PandVanMeting_gebouwklasse> <Meting_geldig_tot> </Meting_geldig_tot> <Pand_registratiedatum> </Pand_registratiedatum> <Pand_postcode>0000AA</Pand_postcode> <Pand_huisnummer>83</Pand_huisnummer> <Pand_gebouwtype>Twee-onder-een-kap / rijwoning hoek</pand_gebouwtype> <Pand_gebouwsubtype>Rijwoning</Pand_gebouwsubtype> </Pandcertificaat> <Pandcertificaat> <PandVanMeting_postcode>1007KE</PandVanMeting_postcode> <PandVanMeting_huisnummer>70238</PandVanMeting_huisnummer> <PandVanMeting_opnamedatum> </PandVanMeting_opnamedatum> <PandVanMeting_berekeningstype>EPA</PandVanMeting_berekeningstype> <PandVanMeting_energieprestatieindex>1.25</PandVanMeting_energieprestatieindex> <PandVanMeting_energieklasse>B</PandVanMeting_energieklasse> <PandVanMeting_gebouwklasse>W</PandVanMeting_gebouwklasse> <Meting_geldig_tot> </Meting_geldig_tot> <Pand_registratiedatum> </Pand_registratiedatum> <Pand_postcode>1007KE</Pand_postcode> <Pand_huisnummer>70238</Pand_huisnummer> <Pand_gebouwtype>Flatwoning (overig)</pand_gebouwtype> <Pand_gebouwsubtype>Tussenvloer</Pand_gebouwsubtype> </Pandcertificaat> </Pandcertificaten> </VolledigeActueleSet> INDEX 6/11

7 4. Inhoud van het mutatiebestand Het dagmutatiebestand bevat mutaties op het totaalbestand van dezelfde maand. Mutatiebestanden moeten in volgorde verwerkt worden om samen met het totaalbestand de actuele stand van een dag op te bouwen. Elk mutatierecord heeft een volgnummer. Het volgnummer van het eerste mutatierecord in het eerste dagmutatiebestand van de maand moet 1 hoger zijn dan het laatste verwerkte volgnummer in het totaalbestand. Wanneer bij verwerking de volgnummers meer dan 1 afwijken, dan zijn er bij de verwerking van mutatiebestanden een of meer bestanden gemist. De verwerking moet dan worden afgebroken. Elk mutatierecord heeft een stuurcode. Stuurcode 1 betekent toevoegen, stuurcode 2 betekent verwijderen. <?xml version="1.0" encoding="utf-8"?> <Mutatieset xmlns=" <Mutatiedatum xmlns=""> </mutatiedatum> <Mutatieberichten xmlns=""> <Mutatiebericht> <Mutatievolgnummer> </Mutatievolgnummer> <Stuurcode>1</Stuurcode> <Pandcertificaat> <PandVanMeting_postcode>3402ZW</PandVanMeting_postcode> <PandVanMeting_huisnummer>20</PandVanMeting_huisnummer> <PandVanMeting_bagverblijfsobjectid> </PandVanMeting_bagverblijfsobjectid> <PandVanMeting_opnamedatum> </PandVanMeting_opnamedatum> <PandVanMeting_berekeningstype>RDEL_2014_1</PandVanMeting_berekeningstype> <PandVanMeting_energieklasse>C</PandVanMeting_energieklasse> <PandVanMeting_gebouwklasse>W</PandVanMeting_gebouwklasse> <Meting_geldig_tot> </Meting_geldig_tot> <Pand_registratiedatum> </Pand_registratiedatum> <Pand_postcode>3402ZW</Pand_postcode> <Pand_huisnummer>20</Pand_huisnummer> <Pand_bagverblijfsobjectid> </Pand_bagverblijfsobjectid> <Pand_gebouwtype>Rijwoning tussen</pand_gebouwtype> </Pandcertificaat> </Mutatiebericht> <Mutatiebericht> <Mutatievolgnummer> </Mutatievolgnummer> <Stuurcode>2</Stuurcode> <Pandcertificaat> <Pand_postcode>3553RW</Pand_postcode> <Pand_huisnummer>57</Pand_huisnummer> <Pand_bagverblijfsobjectid> </Pand_bagverblijfsobjectid> </Pandcertificaat> </Mutatiebericht> </Mutatieset> INDEX 7/11

8 5. Handmatig opvragen bestanden Zodra de gebruiker in EP-online een account met afnemerrechten heeft, dan krijgt hij na inloggen een extra tab Mutatiebestanden te zien. Via deze tab is het mogelijk om het totaalbestand en de dagelijkse mutatiebestanden handmatig op te halen. Door op de naam van het bestand te klikken, start de download. Er zijn twee soorten bestanden te downloaden: een totaalbestand en een dagmutatiebestand. Het dagmutatiebestand bevat de dagelijkse update op het totaalbestand. Het totaalbestand wordt op elke 1e van de maand gegenereerd en begint met een v. Deze set bevat alle geregistreerde geldige energielabels en EI-certificaten met bijbehorende EI-waarde en energielabelklasse. Dagmutatiebestanden worden elke dag gegenereerd en beginnen met een d. Deze sets bevatten updates van het totaalbestand. Alle bestanden zijn gecomprimeerd. De gehanteerde compressiemethode is ZIP. Tab voor afnemers Dag mutatiebestand Volledige maandset INDEX 8/11

9 6. Koppelvlak opvragen bestanden : opvragen download-url Voorbeeld: opvragen totaalbestand. Het downloaden van het totaalbestand en de dagmutatiebestanden kan geautomatiseerd worden door gebruik te maken van de webservice opvragen bestanden. Via deze webservice kan een totaalbestand of een dagmutatiebestand worden opgevraagd. De webservice is te benaderen via onderstaande URLs: <soapenv:envelope xmlns:soapenv=" xmlns:epb="..." xmlns:epb1="..."> <soapenv:header> <epb:epbddownloadmutationfileheader> <epb:username>{inlognaam}</epb:username> <epb:password>{wachtwoord}</epb:password> </epb:epbddownloadmutationfileheader> </soapenv:header> <soapenv:body> <epb1:downloadmutationfile> <epb1:request> <epb1:mutationtype>complete</epb1:mutationtype> </epb1:request> </epb1:downloadmutationfile> </soapenv:body> </soapenv:envelope> Acceptatie: EpbdDownloadMutationFile.asmx Productie: EpbdDownloadMutationFile.asmx Voorbeeld: opvragen dagmutatiebestand. <soapenv:envelope xmlns:soapenv=" xmlns:epb=" xmlns:epb1=" <soapenv:header> <epb:epbddownloadmutationfileheader> <epb:username>{inlognaam}</epb:username> <epb:password>{wachtwoord}</epb:password> </epb:epbddownloadmutationfileheader> </soapenv:header> <soapenv:body> <epb1:downloadmutationfile> <epb1:request> <epb1:mutationtype>mutation</epb1:mutationtype> <epb1:date>{datum: dd-mm-yyyy notatie}</epb1:date> </epb1:request> </epb1:downloadmutationfile> </soapenv:body> </soapenv:envelope> De webservice wordt aangeroepen via onderstaand request. Bij de aanroep dienen de accountgegevens (inlognaam en wachtwoord) te worden meegegeven. Bij het opvragen van het totaalbestand, dient het veld mutationtype de waarde Complete te krijgen. Bij het opvragen van een dagmutatiebestand dient het veld mutationtype de waarde Mutation te krijgen. Tevens dient het veld date te worden gezet op de datum van de dagmutatie die de gebruiker wil ophalen. INDEX 9/11

10 Wanneer een bestand beschikbaar is, zal een antwoordbericht worden teruggegeven. In dit antwoordbericht staat de naam van het bestand, de URL die gebruikt kan worden om het bestand te downloaden en de datum/tijd waarop de geldigheid van de geleverde URL verloopt. De opvraagservice houdt geen historie van bestanden bij. Het opvragen van een totaalbestand of van dagmutatiebestanden levert altijd de bestanden op die horen bij de huidige maand. Voorbeeld antwoordbericht: <soap:envelope xmlns:soap=" xmlns:xsi=" xmlns:xsd=" <soap:body> <DownloadMutationFileResponse xmlns="..."> <EpbdDownloadMutationFile xmlns="..."> <EpbdDownloadMutationFileResponse> <filename>v zip</filename> <downloadurl> <validuntill> t13:55: :00</validuntill> </EpbdDownloadMutationFileResponse> </EpbdDownloadMutationFile> </DownloadMutationFileResponse> </soap:body> </soap:envelope> INDEX 10/11

11 7. Koppelvlak opvragen : direct raadplegen van het register Het koppelvlak opvragen kan gebruikt worden om voor één specifiek adres of BAG-id op te vragen of er een energielabel of EI-certificaat is geregistreerd. De webservice maakt gebruik van onderstaande schema s voor bevraging. In het eerste schema wordt gebruik gemaakt van een postcode, huisnummer en toevoeging om het object te identificeren. In het tweede schema wordt gebruik gemaakt van een BAG verblijfsobject-id om het object te identificeren. Merk op dat in het antwoord twee objecten gespecificeerd zijn. De elementen beginnend met PandVanMeting specificeren gegevens van het object waar de opname van het energielabel heeft plaatsgevonden. De elementen beginnend met Pand specificeren gegevens van het pand waarvoor het energielabel is afgegeven. In geval van registratie op basis van representativiteit is het mogelijk dat het pand van opname afwijkt van het pand waarvoor het energielabel wordt afgegeven. <soapenv:envelope xmlns:soapenv=" xmlns:epb=" xmlns:epb1=" <soapenv:header> <epb:pandenergielabelheader> <epb:username>{inlognaam}/epb:username> <epb:password>{wachtwoord}</epb:password> <epb:versienr>4</epb:versienr> </epb:pandenergielabelheader> </soapenv:header> <soapenv:body> <epb1:getpandenergielabel> <epb1:pand_postcode>{postcode}</epb1:pand_postcode> <epb1:pand_huisnummer>{huisnummer}</epb1:pand_huisnummer> <epb1:pand_huisnummer_toev>{toevoeging}</epb1:pand_huisnummer_toev> </epb1:getpandenergielabel> </soapenv:body> </soapenv:envelope> <soapenv:envelope xmlns:soapenv=" xmlns:epb=" xmlns:epb1=" <soapenv:header> <epb:pandenergielabelheader> <epb:username>{inlognaam}</epb:username> <epb:password>{wachtwoord}</epb:password> <epb:versienr>4</epb:versienr> </epb:pandenergielabelheader> </soapenv:header> <soapenv:body> <epb1:getpandenergielabel> <epb1:pand_verblijfsobjectid>{bag-id}</epb1:pand_verblijfsobjectid> </epb1:getpandenergielabel> </soapenv:body> </soapenv:envelope> Het antwoord wordt gegeven volgens onderstaand schema. <soap:envelope xmlns:soap=" xmlns:xsi=" xmlns:xsd=" <soap:body> <PandEnergieLabel xmlns=" <PandVanMeting_postcode>{postcode}</PandVanMeting_postcode> <PandVanMeting_huisnummer>{huisnummer}</PandVanMeting_huisnummer> <PandVanMeting_huisnummer_toev>{huisnummer toevoeging}</pandvanmeting_huisnummer_toev> <PandVanMeting_gebouwcode>{gebouwcode}</PandVanMeting_gebouwcode> <PandVanMeting_bagverblijfsobjectid>{BAG-id}</PandVanMeting_bagverblijfsobjectid> <PandVanMeting_opnamedatum>{opnamedatum}</PandVanMeting_opnamedatum> <PandVanMeting_berekeningstype>{rekenmethodiek}</PandVanMeting_berekeningstype> <PandVanMeting_energieprestatieindex>{energie index}</pandvanmeting_energieprestatieindex> <PandVanMeting_energieklasse>{energielabel klasse A-G}</PandVanMeting_energieklasse> <PandVanMeting_forfaitaire>{energie index forfaitair}</pandvanmeting_forfaitaire > <PandVanMeting_gebouwklasse>{gebouwklasse}</PandVanMeting_gebouwklasse> <Meting_geldig_tot>{geldigheid meting}</meting_geldig_tot> <Pand_registratiedatum>{registratiedatum}</Pand_registratiedatum> <Pand_postcode>{postcode}</Pand_postcode> <Pand_huisnummer>{huisnummer}</Pand_huisnummer> <Pand_huisnummer_toev>{huisnummer toevoeging}</pand_huisnummer_toev> <Pand_gebouwcode>{gebouwcode}</Pand_gebouwcode> <Pand_bagverblijfsobjectid>{BAG-id}</Pand_bagverblijfsobjectid> <Pand_gebouwtype>{gebouwtype}</Pand_gebouwtype> </PandEnergieLabel> </soap:body> </soap:envelope> INDEX 11/11

12 Dit is een publicatie van: Rijksdienst voor Ondernemend Nederland Croeselaan BJ Utrecht Postbus RE Utrecht T +31 (0) E klantcontact@rvo.nl Deze publicatie is tot stand gekomen in opdracht van het ministerie van Binnenlandse Zaken en Koninkrijksrelaties Rijksdienst voor Ondernemend Nederland januari 2016 Publicatienummer: RVO /HL-DUZA De Rijksdienst voor Ondernemend Nederland (RVO.nl) stimuleert duurzaam, agrarisch, innovatief en internationaal ondernemen. Met subsidies, het vinden van zakenpartners, kennis en het voldoen aan wet- en regelgeving. RVO.nl werkt in opdracht van ministeries en de Europese Unie. RVO.nl is een onderdeel van het ministerie van Economische Zaken.