Juliana van Stolberglaan CA Den Haag Postbus AC Den Haag [Handleiding Generieke interface Energielabels.

Transcriptie

1 Juliana van Stolberglaan CA Den Haag Postbus AC Den Haag Handleiding Generieke interface Energielabels Documentnaam [Handleiding Generieke interface Energielabels.doc]

2 1 Versiehistorie Versie Datum Omschrijving/aanpassingen Auteur Definitieve versie H. Siers (Sogeti) pagina 2 van 11

3 Inhoudsopgave 1 Versiehistorie 2 2 Inleiding Doel Korte Omschrijving Indeling document 4 3 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 4 Interface Actuele Energielabels Attributen Volledige Set Attributen Dagmutatie Set Naamgeving bestanden Moment van genereren FTP-Postbus (bestanden) 9 5 Webservice opvragen pandcertificaat Verzoek Antwoord Toegang WSDL 11 pagina 3 van 11

4 2 Inleiding 2.1 Doel Deze handleiding is bedoeld voor de organisaties die gebruik willen maken van de interface die AgentschapNL aanbiedt om de informatie over actuele Energielabels van panden ter beschikking te stellen aan marktpartijen. De interface bestaat uit 3 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 3 de vormen van aansluiten wordt in deze handleiding uitgelegd hoe die te realiseren. 2.2 Korte Omschrijving Naar aanleiding van de marktvraag omtrent informatie over Energielabels zoals die verstrekt worden volgens de "Energy Performance Building Directive" heeft AgentschapNL 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 AgentschapNL. Het aanvraagformulier staat elders op de website. 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> 2.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 11

5 3 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. 3.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. 3.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 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 11

6 Figuur 1 : Mogelijkheden voor de afnemer voor database met "Volledig actuele set" 3.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 AgentschapNL). 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 11

7 4 Interface Actuele Energielabels AgentschapNL 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. 4.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 VolledigeActueleSet LaatsteVerwerkteMutatieVolgnummer 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 Toelichting Laatste mutatievolgnummer dat verwerkt is in deze set 1 of meer binnen VolledigeActueleSet 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. 4.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 Toelichting pagina 7 van 11

8 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 1 of meer binnen DagMutatieSet 1 = Toevoegen Energielabel, 2 = Verwijderen Energielabel. 1 binnen Mutatiebericht 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. 4.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: 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 gig) 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. 4.4 Moment van genereren De volledige set wordt 1 keer per maand gecreëerd, in principe is dit aan het begin van de maand. De dagmutatieset wordt 1 keer per dag gecreëerd. pagina 8 van 11

9 4.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-SERVER-adres><postbusnaam> waarbij de <postbusnaam> specifiek is voor u als afnemer. Deze dient u dan ook opgegeven te krijgen van AgentschapNL. Gebruikersnaam en wachtwoord waarmee u toegang krijgt tot uw eigen postbus dient u ook van AgentschapNL 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 11

10 5 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 AgentschapNL op te vragen. De operaties bestaan uit: Verzoek Antwoord Deze worden in de volgende paragrafen uitgelegd. 5.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. 5.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 pagina 10 van 11

11 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 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. In alle andere gevallen zal één van de volgende 2 meldingen worden teruggegeven: Technische storing, foutcode <programmamelding>` Service tijdelijk niet beschikbaar` 5.3 Toegang Het adres van deze webservice is <Webserver>EpbdOpvragenPandEnergieLabelService.asmx Gebruikersnaam en wachtwoord waarmee u toegang krijgt tot deze webservice dient u van AgentschapNL te ontvangen. 5.4 WSDL De definities van de berichten zijn gegeven in de volgende bestanden: EpbdOpvragenPandEnergieLabel.wsdl EpbdOpvragenPandEnergieLabelHeader.xsd EpbdOpvragenPandEnergieLabelRequest.xsd EpbdOpvragenPandEnergieLabelResponse.xsd EpbdOpvragenPandEnergieLabelTypes.xsd pagina 11 van 11