Koppeling met MVA database

Transcriptie

1 Koppeling met MVA database Koppeling met MVA database Wijzigingen Benodigde gegevens Globale structuur XML External IDs Verzenden van XML Toevoegen, wijzigen, verwijderen Makelaars koppelen... 5 Bijlage A: XML elementen in <property>... 7 Bijlage B: waarden en betekenissen... 8 Bijlage C: XML <image> element Bijlage D: XML <rightclick> element... 10

2 1. Wijzigingen Versie 3 dd. 1/4/2006 Versie 2 dd. 13/4/2004 Versie 1 dd. 15/7/2003 Opmerking over maximale XML berichtgrootte toegevoegd Opmerking 2 toegevoegd over het verschil tussen het status attribuut en <status> sub-element; URL voor verwerking van XML/laatst verzonden XML aangepast; Elementen <construction>, <elevator>, <housetype> en <mvapublishdate> toegevoegd en element <eigendomsoort> gewijzigd in <ownership-type> in bijlage A; Waarde 0118 (woonhuis), 0503 (bedrijfspand), 0504 (onderstuk), 0705 (winkelpand), 11 (praktijk/woonhuis), 12 (bedrijfspand/woonhuis) en 13 (serviceflat) toegevoegd bij mogelijke objecttypen in bijlage B; Waarden 0801 (bouwgrond), 0804 (grond voor kantorenbouw), 0805 (grond voor winkelbouw) en 0806 (grond voor recreatie) verwijderd uit lijst van mogelijke objecttypen in bijlage B; Standaardwaarden van <rightclick> sub-elementen <application>, <patchlevel> en <version> aangepast in bijlage D. Initiële versie 2

3 2. Benodigde gegevens Externe partij: XML client ID: XML client name: XML koppeling URL: Test account external ID: Test account login: Test account wachtwoord: Test account intranet URL: <Uw bedrijfsnaam> NB: In eerste instantie heeft u geen toegang tot de koppeling; deze valideert het IP adres van de afzender. om uw IP-adres(sen) aan de lijst van toegestane IP adressen te laten toevoegen! 3. Globale structuur XML OG objecten en bijbehorende afbeeldingen worden gekoppeld middels XML data. De globale structuur van deze XML data kan als volgt worden gezien: <rightclick> <children> <propertyfolder> <children> <property> <files> <image> </files> </property> </children> </propertyfolder> </children> </rightclick> Globaal element (algemene parameters voor koppeling) Opsomming van hoofdelementen Propertyfolder, bevat 1 of meer OG objecten Opsomming van OG objecten OG object, ofwel property. Kan woning (zgn. residential class) of bedrijf (commercial class) zijn. Opsomming van bestanden horend bij property. Afbeelding (image) Einde opsomming van bestanden Einde property Einde opsomming van property objecten Einde propertyfolder Einde opsomming hoofdelementen Einde globaal element Het globale rightclick element bevat vijf algemene parameters. Zie hiervoor bijlage D. Het propertyfolder element representeert een verzameling van 1 of meer objecten (properties) van een makelaar. Het is mogelijk om meerdere propertyfolder elementen per XML bestand te specificeren; het is echter aan te raden om zoveel mogelijk de propertyfolders separaat aan te bieden in verband met het localiseren van fouten in de XML. Een property is ofwel een woning, ofwel een bedrijfsobject. Hiertoe bevat elk property element een element genaamd class, dat een element residential bevat of een element commercial. Het type property wordt aangeduid met behulp van het element type; er zijn slechts bepaalde combinaties van residential/commercial en type mogelijk. Zie hiervoor bijlage B. Een property kan 0 of meer afbeeldingen (images) bevatten. Toegestane formaten zijn JPG (maximaal 500 x 500 pixels) en GIF. De bestanden dienen Base64-encoded te worden meegestuurd in de XML. Zie het bijgeleverde XML bestand voor een voorbeeld en bijlage C voor meer informatie. 3

4 4. External IDs Het synchroniseren van objectgegevens en afbeeldingen gaat op basis van zgn. external IDs. Alle objecten in de XML hebben een element <externalid> dat een external ID kan bevatten. Per makelaar krijgt u zo n external ID toegewezen door WebArchitects. De external IDs van propertyfolders, properties en images hebben een onderlinge samenhang, welke is gebaseerd op de external ID van een makelaar. Een voorbeeld: Propertyfolder external ID: MVAEX12345 Property external ID: MVAEX12345xxxxx Image external ID: MVAEX12345xxxxxyy Hierbij dient xxxxx vervangen te worden door een alfanumerieke, unieke identifier voor een OG object, en yy door een alfanumerieke, unieke identifier voor een foto. Als algemene regel geldt: de external ID van properties moeten beginnen met de external ID van de propertyfolder waarin deze staan; op soortgelijke wijze moeten de external IDs van images beginnen met de external ID van de property waarin deze staan. Bijvoorbeeld: <propertyfolder> <externalid>mvaex12345</externalid> <children> <property> <externalid>mvaex </externalid> <files> <image> <externalid>mvaex </externalid> </image> </files> </property> <property> <externalid>mvaex </externalid> <files> <image> <externalid>mvaex </externalid> </image> <image> <externalid>mvaex </externalid> </image> </files> </property> </children> </propertyfolder> 5. Verzenden van XML U kunt uw XML gegevens middels een HTTP POST commando versturen naar onderstaande URL: De XML meegestuurd te worden als variabele genaamd xml. Tevens dient u uw client ID mee te sturen als variabele genaamd id. (Zie hiervoor Benodigde gegevens aan het begin van dit document.) Soms kunnen tekens als ampersand (&) en < > tijdens het verzenden omgeschreven worden naar verkeerde tekens. Om te valideren dat de XML juist is ontvangen op de server, wordt bij elke POST opdracht een bestand weggeschreven dat de ontvangen XML bevat: 4

5 Waarbij xxxxxxxx vervangen dient te worden door uw client ID. (Zie hiervoor Benodigde gegevens aan het begin van dit document.) U kunt twee responses terug krijgen van de server: <response>ok</response>, ofwel <error>[boodschap]</error>. U kunt verifiëren of de gegevens correct zijn verwerkt door in te loggen in het MVA intranet met de aangeleverde login gegevens uit Hoofdstuk 1. Er geldt een maximale berichtgrootte van 5 MB. Berichten die over deze grens heen gaan, zullen HTTP error 403 geven. Omdat dergelijke berichten niet worden verwerkt, zullen deze ook niet opgeslagen worden in het latest-xxxxxxxx.txt bestand. 6. Toevoegen, wijzigen, verwijderen Zodra u voor de eerste keer een object verzendt met een nieuwe external ID, wordt het object automatisch toegevoegd aan de database. Zodra u een object verzendt met een eerder verzonden external ID, zal het eerder toegevoegde object worden gewijzigd. Het verwijderen van objecten gebeurt door het status attribuut van <property> en <image> elementen op deleted te zetten. Stel dat u het eerste object van het voorbeeld in hoofdstuk wilt verwijderen, en de tweede image uit datzelfde voorbeeld. De benodigde XML wordt als volgt: <propertyfolder> <externalid>mvaex12345</externalid> <children> <property status= deleted > <externalid>mvaex </externalid> </property> <property> <externalid>mvaex </externalid> <files> <image status= deleted > <externalid>mvaex </externalid> </image> </files> </property> </children> </propertyfolder> Opmerking 1: Bij een property object hoeft u de afzonderlijke image objecten niet te verwijderen; het systeem verwijdert deze automatisch. Dit geldt overigens niet voor propertyfolder objecten en property objecten daarin. Opmerking 2: het status attribuut van het <property> element staat volledig los van het <status> sub-element van het <property> element. Voorbeeld: indien u het <status> subelement bijvoorbeeld op waarde 7 (ingetrokken) zet, blijft het object zichtbaar op de MVA site maar zal de toevoeging ingetrokken getoond worden. Het object zal dus niet verwijderd worden, hiervoor dient u het status attribuut te gebruiken. 7. Makelaars koppelen Als de tests als succesvol zijn beoordeeld, kan WebArchitects op verzoek de koppeling met bestaande makelaars realiseren. Het huidige aanbod dat op de MVA internet site staat, wordt hierbij door WebArchitects verwijderd. De externe partij dient vervolgens alle objecten van de gekoppelde makelaar opnieuw aan te melden middels de XML koppeling. 5

6 Voor het herstellen van fouten veroorzaakt door verkeerd aanleveren van XML gegevens wordt door WebArchitects het gebruikelijke uurtarief van 95,- berekend. 6

7 Bijlage A: XML elementen in <property> Child element Type Max.len Waarden Omschrijving <externalid> character 20 External ID van object <name> character 150 Naam van object, wordt gebruikt om volgorde te bepalen. Dit dient PLAATSNAAM, Straatnaam nummer extensie te bevatten. <address> character 43 Straatnaam <addressnr> integer 5 Nummer <addressnrext> character 7 Extensie, bijvoorbeeld hs of IV <zipcode> character 10 Postcode <city> character 24 Plaatsnaam <construction> character 1 E,N Bestaande bouw (E=existing) of nieuwbouw (N) <description-plain> character 4000 Omschrijving (zonder HTML) <eigendomsoort> integer 1 Zie bijlage B Vervallen; dit element is vervangen door <ownershiptype> maar zal tot de volgende versie van de XML uitwisseling nog wel worden ondersteund. <elevator> character 1 Y,N Lift aanwezig: ja (Y) of nee (N) <forsale> character 1 Y,N,A Te koop (Y), te huur (N) of veiling(a=auction) <hidden> character 1 Y,N Verborgen (Y) of zichtbaar op internet (N) <investment> character 1 Y,N Beleggingsobject ja (Y) of nee (N) <mvapublishdate> character 10 yyyy-mm-dd Datum waarop pand zichtbaar moet worden op de MVA site. Het object is minimaal 1 dag vanaf het tijdstip van eerste aanlevering onzichtbaar op de MVA site, maar wel zichtbaar voor makelaars in het MVA intranet. <nrrooms> integer 3 Aantal kamers <ownership-type> integer 1 Zie bijlage B Eigendomsoort. <partiallyrented> character 1 Y,N gedeeltelijk verhuurd ja (Y) of nee (N) <price> decimal 9,2 prijs in formaat <priceinclsc> character 1 Y,N prijs inclusief servicekosten ja (Y) of nee (N) <priceincltax> character 1 Y,N prijs inclusief BTW ja (Y) of nee (N) <pricepost> integer 3 Zie bijlage B Prijstoevoeging <pricesold> decimal 9,2 prijs verkocht in formaat <removedate> character 10 yyyy-mm-dd datum waarop pand verwijderd moet worden <status> integer 3 Zie bijlage B Status <surface> integer 3 Grondoppervlak <type> character 10 Zie bijlage B type object <class> XML node Bevat <commercial> of <residential> element <class> <commercial> <class> <commercial> <garage> XML node Bevat elementen ten behoeve van bedrijfs OG objecten character 8 Zie bijlage B garage/parkeergelegenheid 7

8 Bijlage B: waarden en betekenissen XML element Waarde Omschrijving Alleen bij Class <pricepost> 1 per maand 2 niet gebruikt 3 per jaar 4 per m2/maand 5 per m2/jaar 6 kosten koper 7 vrij op naam <type> 01 Woning alleen bij Residential 0101 Eengezinswoning alleen bij Residential 0103 Herenhuis alleen bij Residential 0104 Villa alleen bij Residential 0105 Landhuis alleen bij Residential 0106 Bungalow alleen bij Residential 0107 Woonboerderij alleen bij Residential 0108 Grachtenpand alleen bij Residential 0109 Woonboot alleen bij Residential 0110 Stacaravan alleen bij Residential 0111 Landgoed alleen bij Residential 0112 Recreatiewoning alleen bij Residential 0113 Praktijkwoning alleen bij Residential 0114 drive-in alleen bij Residential 0115 dijkwoning alleen bij Residential 0116 splitlevel alleen bij Residential 0117 patio-bungalow alleen bij Residential 0118 woonhuis alleen bij Residential 02 appartement alleen bij Residential 0201 bovenwoning alleen bij Residential 0202 benedenwoning alleen bij Residential 0203 maisonette alleen bij Residential 0204 galerijflat alleen bij Residential 0205 portiekflat alleen bij Residential 0206 beneden + bovenwoning alleen bij Residential 0207 verzorgingsflat alleen bij Residential 0208 penthouse alleen bij Residential 04 garage alleen bij Residential 05 bedrijfsruimte alleen bij Commercial 0501 productieruimte alleen bij Commercial 0502 opslagruimte alleen bij Commercial 0503 bedrijfspand alleen bij Commercial 0504 onderstuk alleen bij Commercial 06 kantoorruimte alleen bij Commercial 0601 kantoorpand alleen bij Commercial 8

9 XML element Waarde Omschrijving Alleen bij Class 0602 kantooretage alleen bij Commercial 0603 kantoor/woonhuis alleen bij Commercial 07 winkelruimte alleen bij Commercial 0701 winkel alleen bij Commercial 0702 showroom alleen bij Commercial 0703 volumineuze detailhandel alleen bij Commercial 0704 winkel/woonhuis alleen bij Commercial 0705 winkelpand alleen bij Commercial 08 grond alleen bij Residential 0801 bouwgrond Vervallen; gebruik bedrijventerrein 0803 industrieterrein 0804 grond voor kantorenbouw Vervallen; gebruik grond voor winkelbouw Vervallen; gebruik grond voor recreatie Vervallen; gebruik horeca 0901 café 0902 grand café 0903 restaurant 0904 hotel 0905 snackbar 10 agrarisch o.g. 11 praktijk/woonhuis 12 bedrijfspand/woonhuis 13 serviceflat <garage> 1 uitpandige garage 4 inpandige garage 9 parkeerplaats 12 geen garage <ownership-type> 1 volledige eigendom 2 erfpacht <status> 1 beschikbaar 2 onder bod 3 onder optie 4 verkocht onder voorbehoud 5 verkocht 6 verhuurd 7 ingetrokken 8 beschikbaar (nieuw) 50 verkocht voor (toont pricesold op site) <garden> 4 Tuin alleen bij Residential <housetype> 0 (leeg) Geen tuin alleen bij Residential Onbekend/Niet van toepassing alleen bij Residential 1 Vrijstaand alleen bij Residential 9

10 XML element Waarde Omschrijving Alleen bij Class 2 Verspringend alleen bij Residential 3 2/1 kap alleen bij Residential 4 Tussenwoning alleen bij Residential 5 Hoekwoning alleen bij Residential Bijlage C: XML <image> element Child element Type Max.len Waarden Omschrijving <content encoding= encoding type= MIME type length= lengte > character bevat Base64-encoded bestand. Attribuut encoding dient Base64 te zijn. Het MIME type kan zijn image/jpeg of image/gif. De lengte moet de lengte van de decoded file zijn (ongevalideerd) <externalid> character 20 external ID van image <filename> character 100 Oorspronkelijke bestandsnaam <name> character 150 niet gebruikt Bijlage D: XML <rightclick> element Child element Type Max.len Waarden Omschrijving <application> character 50 mva_rc compatibiliteitsparameter <children> XML node bevat te importeren objecten <client> character 5????? bevat uw toegekende client name (zie inleiding van dit document) <patchlevel> numeric 3 9 compatibiliteitsparameter <version> numeric compatibiliteitsparameter 1