01. Introductie
SiteLink is een service die gebruikt kan worden om objectinformatie te downloaden in een vooraf gedefinieerd (Xml) formaat. Deze objectinformatie kan vervolgens uit dat bestand worden gehaald en worden gebruikt om deze bijvoorbeeld te tonen op een externe website van de makelaar.
Nieuwe versie beschikbaar per 26 augustus 2019
Op 26 augustus 2019 is, naast de bestaande versie, een nieuwe versie (3) van SiteLink uitgerold. Deze versie is volledig gesynchroniseerd met de laatste wijzigingen in Kolibri. Mocht u pandtypes of specifieke details missen in de Xml output van de eerdere versies van SiteLink, dan zijn deze details of pandtypes beschikbaar in versie 3.
Algemeen
SiteLink is meertalig opgezet en er wordt de land en cultuur specifieke informatie van het makelaarskantoor van het pand meegeleverd.
Locatie specifieke gegevens
Bij een pand wordt de cultuur (Culture), de geldeenheid (Currency) en de taal (Language) van het makelaarskantoor meegeleverd.
Aan de hand van de cultuur bepaalt de Media Partner hoe de gegevens geïnterpreteerd moeten worden. Geldt in een bepaalde cultuur bijvoorbeeld dat de breedte van een kamer niet de afstand tussen de muren is maar gemeten vanaf het hart van de muren dan is de opgegeven breedte van een kamer dus volgens deze standaard.
De valuta geeft aan welke valuta er gehanteerd moet worden voor de interpretatie van de prijzen. Prijzen bij een pand zijn dus altijd in één valuta. Indien er op een Portal prijzen van panden in meerdere valuta's weergegeven moeten worden dan is de Media Partner dus zelf verantwoordelijk voor de correcte omrekening.
Tot slot bepaalt de taal de standaard taal van de makelaar. Teksten, zoals de advertentietekst, kunnen in meerdere talen aangeleverd worden. Per 'vertaling' wordt de taal van de betreffende vertaling weergegeven. Is er echter geen taal gespecificeerd dan is dit (volgens de makelaar) de standaard tekst, en deze tekst is dus in de standaard taal van het betreffende makelaarskantoor.
Vertalingen
Zoals hierboven staat beschreven kunnen teksten in meerdere talen worden aangeleverd. Welke dat zijn hangt af van de makelaar en zijn instellingen en invoer (in Kolibri).
ID's
Elk pand en elk makelaarskantoor heeft zijn eigen unieke ID. In SiteLink worden hier integers voor gebruikt. Er worden nooit ID's hergebruikt.
Bij een pand kunnen "foreign ID's" worden meegegeven. Dit zijn de ID's waaronder het betreffende pand of makelaarskantoor bij Kolibri bekend is. SiteLink doet niets met deze "foreign ID's", behalve ontvangen van Kolibri en doorsturen naar de Media Partner. De "foreign ID's" kunnen gebruikt worden bij het debuggen; de Media Partner en Kolibri support kunnen dan onderling contact hebben over een bepaald pand en daarbij naar hetzelfde pand verwijzen door gebruik te maken van deze "foreign ID's".
Bij communicatie met SiteLink gebruikt de Media Partner dus nooit foreign ID's.
Datums
Datums en tijden die door SiteLink worden aangeleverd zijn altijd in UTC. Dit geldt dus ook voor datums. Een 'einddatum voorbehoud' is bijvoorbeeld op een bepaald moment in tijd. Dit is één moment, waar je ook maar in de wereld bent. Vandaar dat bij een datum ook de tijd geleverd wordt
Beveiliging
Gebruik van SiteLink vereist een geldig token, welke automatisch per e-mail wordt toegestuurd nadat de makelaar hier om gevraagd heeft vanuit Kolibri.
Het aanroepen van de service zonder geldig token zal leiden tot een HTTP resultaat code 403 (Forbidden).
Objectinformatie downloaden
Zodra een token verkregen is, kan dit gebruikt worden om objectinformatie op te vragen. Het resultaat van een bevraging bestaat uit één bestand waarin de actuele informatie van alle objecten van de makelaar zijn samengevoegd. Op dit moment ondersteunt 'SiteLink' alleen het ZIP-formaat. In het aangeboden ZIP-bestand bevindt zich per object één XML-bestand waarin het bewuste object uitgebreid beschreven wordt.
Het downloaden van het ZIP-bestand gaat via de volgende Url, waar het token een onderdeel van is. In onderstaand voorbeeld is token ABCDEFG als voorbeeld gebruikt.
https://sitelink.kolibri24.com/v3/ABCDEFG/zip
U kunt het downloaden van objectinformatie testen door de bovenstaande Url te kopiëren, ABCDEFG te vervangen door uw token, het resultaat te kopiëren en in de adresbalk van uw browser te plakken. Als het token geldig is, krijgt u uw objectinformatie ter download aangeboden in een ZIP-bestand. Het is echter aan te raden het downloaden en verwerken van deze informatie te automatiseren.
Een voorbeeld van een zip bestand, zoals deze wordt aangeleverd als u met een geldig token de webservice aanroept, kunt u hier downloaden.
Oudere versies
Versie 2
Deze versie bevat de volledige details van objecten in Kolibri, welke op 26 september 2014 beschikbaar waren. Deze upgrade bevat nieuwe (o.a. agrarische) objecttypen en meer details van objecten welke in de loop der tijd aan het objectmodel in Kolibri zijn toegevoegd. U kunt uw objecten downloaden door de volgende Url (let op de 2 in de url!) te gebruiken (waarin u net als voorheen uw eigen token dient in te vullen):
https://MultipleListingService2.wazzupsoftware.com/ABCDEFG/zip
https://sitelink.kolibri24.com/v2/ABCDEFG/zip
Versie 1
Dit is de initiële versie van SiteLink en bevat een beperkte set aan gegevens uit Kolibri. U kunt uw objecten downloaden door de volgende Url te gebruiken (Let op dat u uw token dient in te vullen op de plaats van ABCDEFG):
https://MultipleListingService.wazzupsoftware.com/ABCDEFG/zip