Wiki en FAQ voor de Zabun Api

Guidelines

Stappenplan om de API te gebruiken

Volg onderstaande stappen om vlot met de API aan de slag te gaan.

  1. Vraag uw authenticatie gegevens aan bij de support. U ontvangt bij de activatie een api_key, een client_id, een server_id en uw X-CLIENT-ID (het id van uw bedrijf). Deze kan u steeds heraanvragen via de support. Hou ze geheim. Uw client_id is bovendien gekoppeld aan een bepaald permissieprofiel. Dat profiel bepaalt tot welke endpoints en methodes u toegang heeft. Standaard is dit het profiel Webbouwer — zie "Welke API-calls kan ik uitvoeren met mijn profiel?" hieronder. Promotor en andere profielen zijn ook beschikbaar op aanvraag. Bij de activatie ontvangt u daarnaast een aparte deactivatiesleutel, waarmee u zelf uw api_key kan deactiveren bij een (vermoedelijk) lek — zie "Een API-key deactiveren".
  2. Test de verbinding met de heartbeat endpoint (zie "De verbindingen met de Zabun Api testen").
  3. Verken de swagger om de endpoints, velden en keuzelijsten te leren kennen.
  4. Haal de data op en bewaar ze zelf. Vraag panden, foto's en bestanden niet 'on the fly' op bij elke bezoeker, maar voorzie een eigen database of cache. Zo blijft uw website snel en werkt ze verder als de API even traag of onbereikbaar is, en vermijdt u dat u de rate limit bereikt. Werk incrementeel bij met de delta sync (zie "Het ophalen of synchroniseren van panden"). Maak ook een kopie van foto's en bestanden om kapotte links te vermijden.
  5. Ga live.

Welke API-calls kan ik uitvoeren met mijn profiel?

Uw client_id is gekoppeld aan een permissieprofiel dat bepaalt welke endpoints en methodes u mag gebruiken. Krijgt u een 403 (Verboden) op een endpoint, dan valt die endpoint buiten uw profiel.

Bij elke endpoint staat in de (swagger-)beschrijving welke permissie vereist is. Een endpoint met een "Any"-permissie is toegankelijk zodra u op het bijhorende controller-type minstens één permissie (GET, POST, PATCH of PUT) hebt — het maakt dan niet uit wélke van de vier. Dit is vooral van toepassing op de keuzelijsten (option_items).

Dit zijn de standaard API-calls die een client met het profiel Webbouwer kan uitvoeren voor de koppeling tussen een website en Zabun:

Extra:

Voor bijkomende rechten, zoals het aanmaken en bewerken van panden, het bewerken van contacten en taken, ... heeft u een profiel Promotor nodig. Hiervoor zal de klant een bijkomende offerte moeten goedkeuren.

De LiveAgenda-endpoints vallen onder een apart profiel. Dit vereist een kleine uitbreiding op het Webbouwer-profiel; neem hiervoor contact op met de support.

Welke zaken moeten er extra in orde gebracht worden na het live brengen van de integratie?

U hoeft verder niets door te geven om uw implementatie te voltooien. Wij hebben geen extra configuratie nodig.

Wel nuttig is het doorgeven van het URL-formaat van de pandpagina op uw website aan de support, zodat Zabun rechtstreeks naar een pand op uw site kan linken. Dit is handig voor elke functionaliteit die een directe link naar het pand nodig heeft. De twee voornaamste voordelen zijn:

  1. Het oogje in de media grid. Bij een pand op Zabun verschijnt in de media grid een oogje; de vertegenwoordiger surft daarmee met één klik naar het pand op uw website.
  2. Mailings naar contacten. Panden die als "online" gemarkeerd zijn én een directe URL hebben, worden mee opgenomen in de mailings naar contacten. Een pand zonder link wordt niet mee verstuurd.

Geef het URL-formaat door met de variabele $PROPERTY_AUTOID$ erin, zodat Zabun daar automatisch het juiste Zabun-pandnummer invult. Die link kan u vervolgens op uw eigen website omleiden naar de uiteindelijke panddetailpagina. Voorbeeld: u geeft https://www.website.be/$PROPERTY_AUTOID$ door. Voor pand 4291003 wordt dat https://www.website.be/4291003, dat u omleidt naar https://website.be/tekoop/detail/4291003/.

Dit is echter niet strikt nodig, aangezien u bij het doorgeven van de publicatiestatus van het pand (zie "Pand markeren als ONLINE") ook per pand een URL kan meegeven. Daar kan u ofwel de volledige, vaste URL van het pand doorgeven, ofwel dezelfde $PROPERTY_AUTOID$-variabele gebruiken.

Beveiliging en misbruikpreventie

IP-whitelisting

Als api-key-houder kan u optioneel de toegang tot uw api_key beperken tot bepaalde IP-adressen. Bezorg de gewenste IP-adressen per mail aan de support — dit mag een los adres of een reeks (range) zijn — en wij voegen ze toe aan de whitelist.

Wil u whitelisting weer uitschakelen, of IP's toevoegen of verwijderen, neem dan contact op met de support.

Een API-key deactiveren

Bij de activatie van uw api_key ontvangt u ook een aparte deactivatiesleutel (een token). Hiermee kan u zelf uw api_key onmiddellijk deactiveren, bijvoorbeeld wanneer u vermoedt dat de key gelekt is.

Gebruik hiervoor de endpoint POST auth/v1/api_key/deactivate. Geef uw gewone authenticatie-headers mee, aangevuld met de extra header deactivate_token met uw deactivatiesleutel.

curl -X POST 'https://gateway-cmsapi.v2.zabun.be/auth/v1/api_key/deactivate' \
--header 'X-CLIENT-ID: #X-CLIENT-ID#' \
--header 'client_id: #client_id#' \
--header 'server_id: #server_id#' \
--header 'api_key: #api_key#' \
--header 'deactivate_token: #deactivate_token#'

Na een geslaagde deactivatie is de api_key onmiddellijk onbruikbaar. Voor een heractivatie neemt u contact op met de support.

Spamfiltering op contactformulieren en zoekfiches

Contacten die via POST /contactmessage en POST /contactrequest binnenkomen, worden aan onze kant automatisch gecontroleerd op spam. Dit gebeurt met enkele ingebouwde controles, aangevuld met configureerbare regels. Wordt een contact als spam herkend, dan wordt het verzoek geweigerd met een 400 (Bad request).

Merkt u dat er toch spam doorkomt, of dat legitieme contacten onterecht geblokkeerd worden? Bezorg uw suggesties voor spamregels per mail aan de support, dan bekijken wij of we ze kunnen toevoegen of aanpassen.

Algemeen

Mapping van JSON velden naar Zabun UI velden

Api velden.xlsx Dit bestand is nog niet volledig up-to-date maar bevat wel cruciale variabelen. Gebruik alsnog vooral de swagger voor de velden waar mogelijk.

URL van de API

Gebruik steeds de gateway-versie van de API: https://gateway-cmsapi.v2.zabun.be

Er bestaat een rechtstreekse URL van de API. Deze zal in de nabije toekomst onbereikbaar worden. Schakel over naar de gateway indien u dit nog niet gedaan heeft. De basiswerking van de API is identiek; enkel de URL verschilt.

De swagger/technische documentatie

https://gateway-cmsapi.v2.zabun.be/swagger/index.html

Verplichte authenticatie waardes die nodig zijn om een request te versturen?

Header name Waarde
api_key Uw unieke key. Verkregen bij activatie. Kan heraangevraagd worden via support.
client_id De id van uw client. Verkregen bij activatie. Kan heraangevraagd worden via support.
server_id De vaste id van de API zelf. Verkregen bij activatie. Kan heraangevraagd worden via support.
X-CLIENT-ID De ID van uw bedrijf. Verkregen bij activatie. Kan heraangevraagd worden via support.
X-USER-ID Optioneel. De ID van de gebruiker waarmee u de data wil opvragen, ter identificatie. Wordt automatisch ingevuld als deze header leeg is.

Tip: alles is case sensitive. Als een header met een hoofdletter geschreven is, moet u deze ook zo invullen. Anders kunnen er errors ontstaan.

De verbindingen met de Zabun Api testen

Vervang in onderstaande curl de #...# velden met uw eigen authenticatie waarden.

curl -X GET 'https://gateway-cmsapi.v2.zabun.be/auth/v1/heartbeat' \
--header 'Accept: text/plain' \
--header 'api_key: #api_key#'  \
--header 'client_id: #client_id#' \
--header 'server_id: #server_id#' \
--header 'X-CLIENT-ID: #X-CLIENT-ID#' \

Onderstaande is een verwacht antwoord als alles OK is.

HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/json
Expires: -1
Server: Microsoft-IIS/10.0
X-AspNet-Version: 4.0.30319
Request-Context: appId=cid-v1:863e6ef5-006b-4414-af65-e59561f372b2
Access-Control-Expose-Headers: Request-Context
X-Powered-By: ASP.NET
Date: Tue, 23 Jan 2024 06:55:23 GMT
Connection: close
Content-Length: 15

"V1 xx/xx/xxxx"

Wat is curl?

Het curl commando is een veelgebruikte opdrachtregel-tool in Unix en Unix-achtige besturingssystemen voor het overbrengen van gegevens met URL-syntaxis. Het ondersteunt diverse protocollen zoals HTTP, HTTPS, FTP en SFTP, waardoor het breed inzetbaar is voor het downloaden of verzenden van bestanden van en naar servers. Daarnaast wordt curl vaak gebruikt in scripting en programmeren om API-aanvragen te doen en om met webdiensten te communiceren. Het is ook handig om de API op een simpele manier te testen. De swagger kan curl requests genereren.

curl op Windows

Curl via programmeer tool

Deze methode maakt gebruik van Visual Studio Code, een programma gecreëerd door Microsoft. Dit is een extern programma dat u op eigen keuze en risico gebruikt.

  1. Installeer Visual Studio Code
  2. Voeg de REST Client extensie toe
  3. Maak een bestand aan met de extensie .crl (.http of .rest kunnen ook)
  4. Druk op F1 en kies voor commando: REST Client: Send Request
  5. Resultaat: Status code 200
HTTP/1.1 200 OK
Cache-Control: private
Content-Type: text/html; charset=utf-8
Content-Encoding: gzip
Vary: Accept-Encoding
Date: Tue, 23 Jan 2024 06:50:26 GMT
Connection: close
Content-Length: 10967
Andere externe programma's

Het gebruik van een extern programma is volledig uw eigen keuze. Onderstaande is enkel een suggestie en geen vereiste, en wordt op eigen risico gebruikt.

HTTP statuscodes

HTTP-statuscodes zijn gestandaardiseerde nummers die door een webserver worden teruggegeven om de status van een verzoek aan te geven, zoals of het succesvol was, een fout bevatte, of verdere actie vereist. Ze zijn onderverdeeld in vijf categorieën, die elk een specifieke klasse van antwoorden vertegenwoordigen: informatief (1xx), succes (2xx), omleiding (3xx), cliëntfout (4xx) en serverfout (5xx).

Enkele bekende HTTP-statuscodes zijn:

Authenticatie methoden

API Key

Via drie extra api key headers — client_id, server_id en api_key — kan men rechtstreeks requests uitvoeren zonder de OAuth endpoints te gebruiken. API Key gegevens worden geactiveerd en uitgegeven door de support aan externe partners of webbouwers die een synchronisatie via de API willen opzetten.

--header 'X-CLIENT-ID: #X-CLIENT-ID#' \
--header 'client_id: #client_id#' \
--header 'server_id: #server_id#' \
--header 'api_Key: #api_key#' \

Belangrijk: met de API key headers kan u geen OAuth endpoints aanroepen. Bijgevolg, als u een OAuth Bearer token probeert in te vullen in de Authentication header, zal u altijd een 403 "authentication failed" krijgen. Deze authenticatie krijgt voorrang op de API Key authenticatie. U mag dus geen Authentication header toevoegen.

Sorteren, filteren en paging van data

Basisopstelling voor alle search endpoints:

{
  "paging": {
    "page": 0,
    "size": 100
  },
  "filtering": {
    "full_text": "abcdefgh"
  },
  "sorting": {
    "sort": "MOST_RECENT",
    "order": "ASC"
  }
}

Paging

Voorbeeld: het page veld start met index 0. Als u 21 items met size 10 hebt, dan ziet u op:

Filtering

Sorting

Ophalen van specifieke of alle talen

Gebruik de header Accept-Language met waarde:

Indien deze header niet wordt ingevuld, worden de actieve talen van uw bedrijf doorgestuurd.

Ophalen van geo-data zoals steden en landen

Zabun houdt een eigen lijst van landen en gemeenten/steden bij, gekoppeld via country_geo_id en city_geo_id op onder andere panddata en zoekfiches.

Gebruik GET /geo/cities enkel voor België (country_geo_id = 23). Voor elk ander land gebruikt u POST /geo/cities/search met country_geo_ids en paging: sommige landen hebben een veel grotere stedenlijst, en de niet-gepagineerde GET /geo/cities kan daar een zeer trage en zware response opleveren, met een verhoogd risico dat de verbinding vroegtijdig afgebroken wordt.

Cache deze data verplicht. Landen en gemeenten veranderen praktisch nooit. Cache de resultaten minstens 1 dag, bij voorkeur langer (zie Guidelines). Hebt u deze data regelmatig nodig, dan kan support u op aanvraag ook een statisch JSON-bestand met de geo-data bezorgen, zodat u dit zelf kan inladen zonder de API te belasten.

Panden

Het ophalen of synchroniseren van panden

Er zijn drie manieren om de panden voor uw media te synchroniseren. Ze staan hieronder gerangschikt van aanbevolen naar laatste redmiddel. Het grootste verschil zit in welke panden u terugkrijgt, hoeveel panden dat zijn en hoeveel data u per pand krijgt.

# Manier Endpoint Welke panden Data per pand Gebruik
1 Delta sync (aanbevolen) POST /property/media-sync/{media_id}/delta Enkel de panden die gewijzigd zijn sinds uw laatste sync — inclusief panden die offline moeten (met online = false) Minimaal: identificatie, statusvlaggen, online-vlag, wijzigingsdatums, categorie... De volledige data haalt u apart op Best voor het synchroniseren en up to date houden van panden.
2 Media sync (alternatief) POST /property/media-sync/{media_id} Enkel de panden die op dit moment online staan voor de media Uitgebreide samenvatting per pand Als oplijsting van panden
3 Property search (laatste redmiddel) POST /property/search Alle panden die aan uw eigen filters voldoen (niet media-gestuurd) Uitgebreide samenvatting per pand Custom oplijsting

De variabele {media_id} vervangt u door het media-ID van uw website. Dit is doorgaans 14 — het id dat standaard overeenkomt met het medium "Website via API" in Zabun — maar afhankelijk van uw configuratie kan dit een ander id (en een andere naam) zijn. Wanneer een pand op uw website getoond mag worden, activeert de vertegenwoordiger dat pand in Zabun voor dat medium via het tabblad Media. Het pand wordt daarmee als "online" gemarkeerd, wat betekent dat het op dat medium getoond mag worden. Via de API haalt u vervolgens alle panden op die voor dit medium geactiveerd zijn en dus op uw website mogen verschijnen.

Alle drie de endpoints deactiveren automatisch de panden voor de media die "spookpanden" geworden zijn (panden die nog online staan maar intussen inactief, gearchiveerd of verwijderd zijn).

1. Delta sync — de aanbevolen en primaire manier

POST /property/media-sync/{media_id}/delta

Dit is de meest efficiënte manier om te synchroniseren. U geeft in de filtering de last_changed_date mee (uw laatste sync-datum). De endpoint geeft dan enkel de panden terug die sindsdien nieuw of gewijzigd zijn, of offline moeten — de "delta". Kijk zeker de waarde van de variabele online na.

curl --location --request POST 'https://gateway-cmsapi.v2.zabun.be/api/v1/property/media-sync/14/delta' \
--header 'X-CLIENT-ID: #X-CLIENT-ID#' \
--header 'client_id: #client_id#' \
--header 'server_id: #server_id#' \
--header 'api_key: #api_key#' \
--header 'Content-Type: application/json' \
--data '{
    "paging": { "page": 0, "size": 100 },
    "filtering": {
        "last_changed_date": "2024-05-01T00:00:00Z",
        "retrieve_future_properties": false
    }
}'

Belangrijk om te weten:

2. Media sync — het alternatief

POST /property/media-sync/{media_id}

curl --location --request POST 'https://gateway-cmsapi.v2.zabun.be/api/v1/property/media-sync/14' \
--header 'X-CLIENT-ID: #X-CLIENT-ID#' \
--header 'client_id: #client_id#' \
--header 'server_id: #server_id#' \
--header 'api_key: #api_key#' \

Deze endpoint geeft enkel de panden terug die op dit moment publiek staan (= groen huisje, status actief, niet verwijderd en niet gearchiveerd) én geactiveerd zijn voor de media binnen de ingestelde start- en eventuele (geplande) einddatum.

3. Property search — het laatste redmiddel

POST /property/search

Als u alle panden wil ophalen, of met uw eigen filters en zonder een media te gebruiken, dan kan de standaard search endpoint gebruikt worden.

curl --location --request POST 'https://gateway-cmsapi.v2.zabun.be/api/v1/property/search' \
--header 'X-CLIENT-ID: #X-CLIENT-ID#' \
--header 'client_id: #client_id#' \
--header 'server_id: #server_id#' \
--header 'api_key: #api_key#' \
--data-raw   ''

Indien u de media sync wil nabootsen met deze search endpoint, moet u ten minste volgende filters meegeven:

public: true,
active_media_ids: [#media_id#], //Dit zal 14 zijn

Daarom raden we aan om liever de delta of de media sync te gebruiken als u de vertegenwoordiger vanuit Zabun de controle wil geven over de beschikbare panden.

always_show_all_children: zal altijd alle kind-objecten in de lijst stoppen ongeacht de filtering. Deze kinderen tellen niet mee voor het aantal panden en ook niet voor de paging size limiet.

Gebruik de search enkel met toestemming van uw client.

Enkel projecten ophalen

Om enkel projecten op te halen, kan u op twee manieren werken:

  1. Zelf in de lijst van panden filteren op de variabele is_project = true.
  2. Aan de "Property Search" de filter kind: PROJECT_ONLY meegeven om enkel projecten binnen te halen.

Enkel "nieuwbouw" panden ophalen

Om nieuwbouwpanden op te halen (m.a.w. panden met eigenschap "nieuwbouw"), moet u zelf in de pandenlijst filteren op de variabele development = true.

Nieuwbouwpanden kunnen zowel gewone panden als projecten zijn. Als u enkel nieuwbouwprojecten wil (m.a.w. een pand van type "project" met eigenschap "nieuwbouw"), dan combineert u filters op één van deze manieren:

  1. Zelf filteren op is_project = true én development = true.
  2. Aan de "Property Search" de projectfilter toevoegen + zelf filteren op development = true.

Enkel panden met een bepaalde sticker ophalen

Een sticker (bijvoorbeeld "In optie", "Nieuw" of "In prijs verlaagd") zit als sticker_id in de panddata — zowel in de volledige panddata als in de samenvatting per pand in de pandenlijsten. De beschikbare stickers met hun id haalt u op via GET /property/stickers. U kan op twee manieren enkel de panden met een bepaalde sticker ophalen:

  1. Zelf in de lijst van panden filteren op de variabele sticker_id.
  2. Aan de "Property Search" de filter sticker_ids meegeven om enkel panden binnen te halen waarvan de sticker_id in uw opgegeven lijst zit.

Alle data van een pand ophalen

Bovenstaande sync-endpoints halen een lijst van panden op met een beperkte collectie van data (= variabelen). Om alle data van een pand te verkrijgen, moet u dit pand rechtstreeks opvragen via GET /property/{property_autoid}.

curl --location --request GET 'https://gateway-cmsapi.v2.zabun.be/api/v1/property/{property_autoid}' \
--header 'X-CLIENT-ID: #X-CLIENT-ID#' \
--header 'client_id: #client_id#' \
--header 'server_id: #server_id#' \
--header 'api_key: #api_key#' \
--data-raw   ''

Gerelateerde data of data op basis van IDs

Veel velden in de panddata zijn geen leesbare waarden op zich, maar verwijzingen. Er zijn twee soorten:

Keuzelijsten en vaste waardebenamingen

Velden zoals status_id, transaction_id, type_id, building_type_id, ... bevatten enkel een ID. Om de leesbare naam te vinden, haalt u de bijhorende keuzelijst op via het option endpoint en zoekt u het ID op in die lijst. Voor dit soort velden hebt u altijd het option endpoint nodig; de naam zit nooit rechtstreeks in de panddata. Cache deze keuzelijsten (zie Guidelines).

Hieronder enkele belangrijke keuzelijstvelden met voorbeelden:

Dezelfde werkwijze geldt voor alle andere ID-velden (hoofdtypes via GET /property/head_types, voorzieningen via GET /property/facilities, ...).

Praktisch alle keuzelijstdata kan in één keer opgehaald worden via de GET /property/option_items endpoint.

Uitgebreide data

Met de parameter ?extended=true op de GET property endpoint krijgt u extra ("extended") data bij een pand. Deze parameter vertraagt de request en verhoogt de responsgrootte, dus gebruik hem enkel wanneer u die extra data nodig hebt.

curl --location --request GET 'https://gateway-cmsapi.v2.zabun.be/api/v1/property/{property_autoid}?extended=true' \
--header 'X-CLIENT-ID: #X-CLIENT-ID#' \
--header 'client_id: #client_id#' \
--header 'server_id: #server_id#' \
--header 'api_key: #api_key#' \
--data-raw   ''

Er zijn twee soorten extended data: Velden die enkel bij extended=true verschijnen (ze zitten niet in de gewone response):

Velden die al in de gewone response zitten, maar uitgebreider worden bij extended=true:

In de swagger documentatie staat aangeduid welke velden extended zijn.

De gemeente (geo) is een speciaal geval. De gemeente van een pand zit standaard als city_geo_id in de adresdata. De volledige gemeente-info krijgt u ofwel inline via ?extended=true (zie hierboven), ofwel door de gemeente apart op te vragen via GET /geo/cities/{city_geo_id} met dat id. Dit apart ophalen geldt enkel voor geo-data en werkt gelijkaardig aan een keuzelijst.

curl --location --request GET 'https://gateway-cmsapi.v2.zabun.be/api/v1/geo/cities/{city_geo_id}' \
--header 'X-CLIENT-ID: #X-CLIENT-ID#' \
--header 'client_id: #client_id#' \
--header 'server_id: #server_id#' \
--header 'api_key: #api_key#' \
--data-raw   ''

Prijs zichtbaar

In tegenstelling tot een portaal halen wij de prijs niet automatisch weg uit de panddata in de API. De logica voor het tonen of verbergen van de prijs moet door de website zelf toegepast worden. Bij de panddata, in zowel de GET als de SEARCH, vindt u de variabele price_visible. Indien deze false is, mag u de prijs niet tonen (behalve als anders afgesproken met de makelaar).

Uitleg bij specifieke pandvelden

Online- en statusvelden

publish = deze vlag bepaalt of het pand online zichtbaar mag zijn (true) of offline is (false). Deze vlag gebruikt de onderstaande velden om dat te bepalen.

Dit is enkel op basis van panddata, en mist de media-data. Om de online status voor een specifieke media te verkrijgen, moet u één van de media-sync endpoints gebruiken.

Transactiegeschiedenis

history_transaction = een historiek van transacties (te koop, te huur, ...). In deze lijst kan u zien wanneer de transactie is aangepast. Deze lijst is aflopend gesorteerd op datum, m.a.w. de meest recente aanpassing staat bovenaan. Ze bevat ook de initiële transactie, die dus helemaal onderaan staat.

Bepalen hoe lang een pand een bepaalde transactie (te koop, te huur, ...) heeft

Met het datumveld date_history kan u berekenen hoelang het pand een transactie al heeft. Voor de meest recente transactie neemt u dat veld en trekt u het af van vandaag. Voor een vorige transactie trekt u die datum af van de datum van de transactie die erboven staat.

Endpoint GET /property/{property_autoid}/history/transaction toont dezelfde data als bovenstaande variabele van de panddata, waarbij u ook kan filteren en sorteren.

Oppervlaktes en kadastraal inkomen

Beschikbaar in de panddata via GET /property/{property_autoid}:

Bouwtechnische informatie

In Zabun te vinden onder de tab technisch. Beschikbaar in de panddata via GET /property/{property_autoid}.

technicals, technical_dropdowns en de evaluation-lijsten zijn ook terug te vinden onder GET /property/option_items.

Overstroming

Scores

Op pandniveau bestaan de scores flooding_building_score (= g score) en flooding_parcel_score (= p score). Deze geven de effectieve waarde terug: A, B, C, D of 0 voor onbekend.

Overstromingsgevoeligheid

o_level_flooding_sensitivity_id



De waardebenamingen kan u opvragen via GET /property/flooding_sensitivities.

In dit geval betekent ID 3 = Niet overstromingsgevoelig.

Afgebakende overstromingszone

o_level_flooding_zone_id



De waardebenamingen kan u opvragen via GET /property/flooding_zones.

In dit geval betekent 3 = niet van toepassing.

Vergunningen en juridische maatregelen

Deze velden bevatten meestal enkel een ID. De leesbare betekenis haalt u op via het bijhorende option endpoint. Tip: alle _ynu velden zijn variabelen met als waarde "Ja", "Nee" of "Onbekend" (in het Engels: ['YES', 'NO', 'UNKNOWN']).

Recht van voorkoop

presale_right_ynu



Verkavelingsvergunning

Omgevingsvergunning voor het verkavelen van gronden. allocation_license_ynu



Verkooprecht / bouwvergunning (handhaving)

building_license_id (integer). De waardebenamingen van de ID vraagt u op via GET /property/building_licenses.





In dit voorbeeld betekent 1 = bouw vergund.

Gerechtelijke of bestuurlijke maatregel (dagvaarding)

Dagvaarding voor stedenbouwkundige overtreding, ook "omgevingsvergunning voor stedenbouwkundige handelingen". town_planning_violation_id (integer). De waardebenamingen van de ID vraagt u op via GET /property/town_planning_violations.





In dit voorbeeld betekent 0 = geen rechterlijke herstelmaatregel of bestuurlijke maatregel opgelegd.

EPC en EPB

EPC label

Onderdeel van de panddata via GET /property/{property_autoid}.

EPC certificaat en referentie

Het EPC-certificaatveld — namelijk of het aanwezig is — is gemapt met het veld certificate_ep_ynu.

De referentie van het epc-document is te vinden in de variabele epc_reference.

Verschil tussen de gewone EPC velden en de _shared velden

De gewone epc en epb zijn voor volledige huizen of uw eigen appartement; de _shared versies zijn voor het gehele gebouw bij een appartement of andere panden waar er een gedeelde layout is.

Alle epc-velden worden gebruikt voor de epb-waarden, behalve de referentie. Dit komt omdat de referentie andere regels heeft qua formaat, die niet samen geprogrammeerd kunnen worden met het epc-referentieveld. Daarom bestaat er een epb_reference, maar geen epb_value of custom_epb_label: de aparte regels voor de waarde en de label van de epb zijn wel geprogrammeerd in de epc-velden.

Pand markeren als ONLINE

Wanneer u een pand synchroniseert en online brengt op uw website, is het interessant om dit door te geven aan de CMS Api. Deze gegevens worden gebruikt om aan de vertegenwoordiger te tonen dat het pand succesvol gesynchroniseerd is en online staat, waarbij een link naar het pand op de website wordt toegevoegd aan Zabun.

Geef via het veld sync_result_url de URL van het pand op uw website mee. Deze link voedt het oogje in de media grid en zorgt ervoor dat het pand mee opgenomen wordt in de mailings naar contacten (zie "Welke zaken moeten er extra in orde gebracht worden na het live brengen van de integratie?"). Geef hier ofwel de volledige, vaste URL van het pand door, ofwel een URL met de variabele $PROPERTY_AUTOID$, die Zabun dan invult met het Zabun-pandnummer.

curl -X POST 'https://gateway-cmsapi.v2.zabun.be/api/v1/property/{property_autoid}/media/14/start-stop' \
--header 'Content-Type: application/json'  \
--header 'Accept: application/json' \
--header 'X-CLIENT-ID: #X-CLIENT-ID#' \
--header 'client_id: #client_id#' \
--header 'server_id: #server_id#' \
--header 'api_key: #api_key#' \
-d '{ "start_media": true,
"sync_result_url": "https://www.website.be/$PROPERTY_AUTOID$" 
}'

U kan via deze endpoint ook aangeven wanneer een pand op uw website wordt bijgewerkt of offline gehaald. Deze drie JSON body's zijn de mogelijke waarden. U kan ze niet door elkaar gebruiken:

{"start_media": true}   => "Het pand is aangemaakt op de website en online te bezichtigen"
{"update_media": true}  => "Het pand is bijgewerkt"
{"stop_media": true}    => "Het pand is offline gehaald en niet meer te vinden op de website"

Media categorie beheren en toewijzen aan panden voor op uw website

In Zabun is het mogelijk om een categorie te kiezen bij het activeren van een pand voor de geselecteerde media. Om een categorie beschikbaar te maken, moet u deze eerst via de API aanmaken voordat ze in Zabun geselecteerd kan worden. Hieronder de verschillende stappen.

1. Ophalen van beschikbare categorieën Dit kan via GET /media/14/categories.

curl --location --request GET 'https://gateway-cmsapi.v2.zabun.be/api/v1/media/14/categories' \
--header 'X-CLIENT-ID: #X-CLIENT-ID#' \
--header 'client_id: #client_id#' \
--header 'server_id: #server_id#' \
--header 'api_key: #api_key#' \
--header 'Content-Type: application/json'

2. Aanmaken van categorieën Dit kan via POST /media/14/categories. Enkel de name is verplicht. U krijgt een object terug met daarin id. Dit is de category_id, die gebruikt wordt om de categorie te koppelen aan het pand.

curl --location --request POST 'https://gateway-cmsapi.v2.zabun.be/api/v1/media/14/categories' \
--header 'Content-Type: application/json'  \
--header 'Accept: application/json' \
--header 'X-CLIENT-ID: #X-CLIENT-ID#' \
--header 'client_id: #client_id#' \
--header 'server_id: #server_id#' \
--header 'api_key: #api_key#' \
--data '{
    "name": {
        "NL": "Mijn nieuwe categorie",
        "FR": "Ma nouvelle catégorie"
    }
}'

Voorbeeld antwoord:

{
    "name": {
        "nl": "Mijn nieuwe categorie",
        "fr": "Ma nouvelle catégorie"
    },
    "id": 2,
    "media_id": 14,
    "bedrijf_id": ####
}

3. Verwijderen van categorieën Dit kan via DELETE /media/14/categories/{category_id}. De category_id vindt u in de antwoorden van stap 1 of 2, in de variabele id. Pas op met het verwijderen van categorieën. Dit heeft een direct gevolg voor de panden in uw media syncs.

curl --location --request DELETE 'https://gateway-cmsapi.v2.zabun.be/api/v1/media/14/categories/2' \
--header 'Content-Type: application/json'  \
--header 'X-CLIENT-ID: #X-CLIENT-ID#' \
--header 'client_id: #client_id#' \
--header 'server_id: #server_id#' \
--header 'api_key: #api_key#' \

U krijgt een 200 OK met body true als antwoord indien het verwijderen gelukt is.

4. Een categorie aan een pand toewijzen Dit kan via Zabun als er categorieën bestaan voor de media.

5. Verkrijgen van de categorie voor een pand in de API De variabele active_category_id (een lijst van integer ids = de category ids) wordt teruggegeven in de response van zowel POST /property/media-sync/14 (de media sync) als POST /property/media-sync/14/delta (de delta sync), indien er minstens 1 categorie geselecteerd is. U kan de variabele voor de panden ook terugvinden via GET /media/{media_id}/properties.

Ophalen van fotos bij panden

Dit kan via GET /property/{property_autoid}/photos. U krijgt een url die u kan gebruiken om een kopie te downloaden, of rechtstreeks te gebruiken op uw website. Standaard zitten foto's ook bij de GET Property endpoint.

[
  {
    "property_id": 4129931,
    "type_id": 0,
    "url": "https://files.zabun.be/upload/2791/images/c51b4ce53616061458a379ee583238225ff4670b6cef7f5aa9dc0b5d5068dbc0.jpg",
    "autoid": "3746002791000001048",
    "file_autoid": "3746002791000001919",
    "url_thumbnail": "https://files.zabun.be/upload/2791/images/c51b4ce53616061458a379ee583238225ff4670b6cef7f5aa9dc0b5d5068dbc0_tn.jpg",
    "reference": "pexels-asad-photo-maldives-1268871.jpg",
    "file_size": 494047,
    "index": 1,
    "creation": "2024-04-08T13:21:12+02:00",
    "creation_person_id": 18454,
    "changed": "2024-04-08T13:21:12+02:00",
    "changed_person_id": 18454,
    "company_id": 2791,
    "comment": {}
  }
]

Gelieve volgende puntjes in acht te nemen:

Zie ook: "Moeten bestanden en foto's (=Media) gedownload worden en mogen de directe URL gebruikt worden".

Aanpassen van foto- en bestandsfiltering op type die ingesteld zijn in de admin van uw Zabun

De filters

Bij het syncen van foto's en bestanden is het mogelijk om een filter toe te passen op hun type. De volgende drie regels worden vaak toegepast:

De filters toepassen op uw website

  1. Automatisch Via de GET property endpoint geeft u de media_id mee als query-parameter. Hierbij worden de bovenstaande filters automatisch toegepast op de foto- en bestandslijsten die u meekrijgt in de panddata. Indien u geen media_id meegeeft, dan wordt er geen filter toegepast en krijgt u alle foto's en bestanden terug, ongeacht hun type (dus ook zonder type). De aparte endpoints om foto's en bestanden van een pand op te halen, worden nooit automatisch gefilterd. Bijvoorbeeld: /api/v1/property/{property_autoid}?media_id=14.

  2. Manueel

Ophalen van video's bij panden

Video's werken op dezelfde manier als foto's. U haalt ze op via GET /property/{property_autoid}/videos. Standaard zitten de video's ook al bij de GET Property endpoint.

Een video verwijst via de url naar de videobron. Dit is meestal een externe dienst zoals YouTube of Vimeo; u hoeft hier dus geen kopie van te downloaden en kan de url rechtstreeks gebruiken of embedden op uw website. De volgorde bepaalt u met index. De benamingen van de types haalt u op via GET /property/videos/types.

[
  {
    "autoid": "3746002791000002051",
    "property_id": 4129931,
    "type_id": 0,
    "url": "https://www.youtube.com/watch?v=xxxxxxxxxxx",
    "index": 1,
    "creation": "2024-04-08T13:21:12+02:00",
    "creation_person_id": 18454,
    "changed": "2024-04-08T13:21:12+02:00",
    "changed_person_id": 18454,
    "company_id": 2791
  }
]

Wat zijn documenten en waarom u ze niet wilt op uw website

Documenten zijn realtime gegenereerde bestanden op basis van een vooringestelde template. Deze bestanden kunnen affiches zijn met panddata, maar ook statistieken van contacten en hun gegevens, zoals maandrapporten. Documenten zijn dus vooral voor intern gebruik bedoeld en worden best niet zomaar op de website aangeboden. Het is uiteraard mogelijk om een document in Zabun te genereren en dit op te laden bij de bestanden van een pand, om het dan via GET /property/{property_autoid}/files op te halen.

Als u toch documenten (en de generatie ervan) op de website wil tonen, dan moet u hiervoor toestemming vragen aan Zabun. Deze zijn namelijk niet standaard inbegrepen in het webbouwerprofiel.

Indelingen (layouts)

Om de beschikbare indelingen te verkrijgen, kan men GET /property/layouts oproepen. Deze data bevindt zich ook in /property/option_items onder "layouts".

Het resultaat is een lijst van IDs met benamingen en andere data over de indelingen die het bedrijf heeft. Hieronder zitten standaard indelingen, zoals slaapkamer: ID = 1 en badkamer: ID = 5, en ook custom indelingen met hun eigen ID.





Foto toont een voorbeeld van woonkamer, met ID = 7.

Deze IDs moeten gekoppeld worden met de layout_id die men vindt in de panddata onder "layouts". Panddata via GET /property/{property_autoid}:



In deze foto gaat het dus over een woonkamer, doordat layout_id gelijk is aan 7. Andere data die men vindt over een indeling van een pand is opp., verdiep, aantal, sortering en commentaar in alle actieve talen als ze iets ingevuld hebben.

Om het aantal indelingen te tellen, moet men de volgende som doen: tel alle count-waarden op van de items in de indelinglijst die voor een layout_id voorkomen. Het is namelijk mogelijk dat een bepaalde layout meerdere keren voorkomt in de layouts lijst, aangezien men in Zabun dezelfde indelingen kan opsplitsen in meerdere regels, om zo een onderscheid te maken tussen elkaar.

Een voorbeeld: men maakt een regel voor slaapkamer aan met als commentaar "gelijkvloers" en vult het aantal 2 in. Men maakt nog een regel voor slaapkamer aan met als commentaar "bovenverdiep" en vult het aantal 3 in. Het resultaat is een "layouts" lijst met 2 items. Beide items hebben layout_id = 1, waarvan de ene count = 2 en de andere count = 3 heeft. In totaal zijn er 5 slaapkamers in het pand.

Aanmaken van een nieuw pand

Deze endpoint is niet beschikbaar bij het gewone webbouwer profiel.

curl --location "https://gateway-cmsapi.v2.zabun.be/api/v1/property" \
--header 'X-CLIENT-ID: #X-CLIENT-ID#' \
--header 'client_id: #client_id#' \
--header 'server_id: #server_id#' \
--header 'api_key: #api_key#' \
--header "Content-Type: application/json" \
--data "{
    \"office_autoid\": 0,
    \"transaction_id\": 1,
    \"type_id\": 26,
    \"status_id\": 1,
    \"show\": 1,
    \"mandate_type_id\": 1,
    \"mandate_start\": \"2024-05-03T09:39:48.423Z\",
    \"price\": 250000,
    \"responsible_salesrep_person_id\": #X-USER-ID#,
    \"address\": {
        \"city_geo_id\": 1001082,
        \"number\": \"180\",
        \"country_geo_id\": 23,
        \"street_translated\": {
            \"nl\":\"vijfseweg\"
        }
    }
}"

Daarnaast zijn de volgende velden optioneel, maar interessant om mee te geven:

Contacten

Doorsturen van een contactformulier door/Aanmaken van een contact als kandidaat van een pand

Deze endpoint is nuttig wanneer u een contact wilt aanmaken op basis van een binnenkomend contactformulier. Hierbij wordt in Zabun automatisch een taak aangemaakt bij zowel het contact als het pand waarop gereageerd werd. Standaard wordt hiervoor het taaktype WEB gebruikt. Daarnaast kunnen nog een aantal bijkomende acties uitgevoerd worden, zoals het versturen van een automatische bedankingsmail naar de kandidaat of het aanmaken van een automatische zoekfiche.

Indien automatische zoekfiches zijn ingeschakeld in de Zabun-instellingen, kan deze endpoint ook een zoekfiche aanmaken op basis van het pand waarop de contactpersoon reageert. Hierbij worden onder andere criteria zoals budget, pandtype en transactietype automatisch overgenomen.

Wanneer de zoekfiche wordt aangemaakt, kan de contactpersoon vervolgens automatische e-mails ontvangen met gelijkaardige panden uit het portefeuille. Hiervoor moet de klant deze functionaliteit hebben geactiveerd in Zabun en moet de contactpersoon expliciet toestemming geven via de velden marketing_opt_in en mailing_opt_in.
Deze toestemmingen worden doorgaans geregistreerd via een selectievakje op het contactformulier.

Let op: contacten die door onze spamdetectie of blacklist als spam herkend worden, worden geweigerd met een 400 (validatie error).

curl --location --request POST 'https://gateway-cmsapi.v2.zabun.be/api/v1/contactmessage' \
--header 'Content-Type: application/json' \
--header 'X-CLIENT-ID: #X-CLIENT-ID#' \
--header 'client_id: #client_id#' \
--header 'server_id: #server_id#' \
--header 'api_key: #api_key#' \
--data '{
    "contact": {
        "email": "[email protected]",
        "first_name": "Jan",
        "last_name": "Jansens",
        "marketing_opt_in": true,  //Is contact akkoord met privacy beleid?
        "mailing_opt_in": true, //Mag Contact Gemailed worden?
        "phone": "496xxxxxx",
        "phone_cc": "32",
        "language": "NL",
        "media_id": 14 //Optioneel: de website/media waarvan het formulier komt
    },
    "message": {
        "text": "Kopen",
        "property_id": #property_autoid#,
        "info": [
            "info1",
            "info2",
            "info3"
        ]
    }
}'

Belangrijke of verplichte velden

Bron contactformulier aangeven

Deze optionele variabele media_id (in het contact-object) duidt aan van welk medium/website het contactformulier afkomstig is. De aangemaakte contacttaak (of, bij een property_id, de contactaanvraag op het pand) wordt aan dat medium gekoppeld, en de naam van het medium wordt als bron ("afkomstig van") in Zabun bewaard. Zo krijgt de vertegenwoordiger een correcte bronvermelding en kloppen uw statistieken per website.

Geeft u geen media_id mee, dan kiest het systeem zelf een medium, in deze volgorde:

  1. de actieve media van het opgegeven pand (property_id), indien er een pand is meegegeven;
  2. anders de standaard actieve eigen-website-media van het bedrijf.

Bij bedrijven met meerdere websites kan die automatische keuze verkeerd uitvallen. Geef daarom bij voorkeur zelf de juiste media_id mee — doorgaans dezelfde media als waarmee u synchroniseert (bv. 14).

Doorgeven van de gestelde vraag

contact > question is een oude variabele die enkel nog als backup gebruikt wordt voor als message > text leeg is. Gelieve dus text te gebruiken. message > info kan gebruikt worden om extra informatie of vragen toe te voegen. Dit is handig als u keuzeopties (= checkboxes) toevoegt aan uw contactformulier. Deze worden na de vraag in de taak gezet in het volgende formaat: vraag + "Vraagt info over:" + elk item in message.info, gesplitst met een ','.

Voorbeeld: message.text = "Ik wil graag een huis kopen", message.info = ["Ik wil A weten", "Ik wil B zien"] Resultaat beschrijving taak (contactformulier) = Ik wil graag een huis kopen. Vraagt info over: Ik wil A weten, Ik wil B zien

Een categorie toevoegen aan een contact

Enerzijds kan u altijd categorieën toevoegen aan een contact via de rechtstreekse endpoints:

Bij de contact-endpoints — zowel de POST en PATCH contact als de POST contactmessage — kan u ook direct een lijst van categorieën meegeven via de variabele categories. Deze lijst moet dan de IDs bevatten van de categorieën die u aan het contact wilt koppelen.

U kan de bestaande categorieën van uw bedrijf vinden via GET /contact/categories.

Aanmaken van een nieuw contact met bijhorende zoekfiche

curl --location --request POST 'https://gateway-cmsapi.v2.zabun.be/api/v1/contactrequest' \
--header 'Content-Type: application/json' \
--header 'X-CLIENT-ID: #X-CLIENT-ID#' \
--header 'client_id: #client_id#' \
--header 'server_id: #server_id#' \
--header 'api_key: #api_key#' \
--data '{
    "contact": {
        "last_name": "Jansens",
        "email": "[email protected]",
        "language": "NL",
        "mailing_opt_in": true, //Mag Contact Gemailed worden?
        "marketing_opt_in": false,  //Is contact akkoord met privacy beleid?
    },
    "request": {
        "price": {
            "min" : 250000,
            "max" : 750000
        },
        "sales_rep": #person_id#,
        "bedrooms": {
            "min": 1,
            "max": 3
        },
        "bathrooms": {
            "min": 1,
            "max": 3
        },
        "price": {
            "min": 1000,
            "max": 500000
         },
         "cities": [
            1001082 //Waregem
         ],
        "surface": {
            "min": 500,
            "max": 9000
         },
        "transactions": [
            1 //te koop
         ],
        "types": [
            1 //appartement
         ]
   }
}'

Deze payload toont enkel de verplichte velden; zie swagger voor de volledige payload. Hieronder nog extra uitleg voor de verplichte of belangrijke velden:

Voor zowel het contact als de zoekfiche is de status altijd default "actief". U kan dit niet meegeven in deze request. Met de nodige permissies kan u dit wel achteraf patchen.

Toevoegen van een bestand bij een bestaande contact

Via POST /contact/{contact_autoid}/files kan een bestand opgeladen worden via de API. Als data/body van de request geeft u het effectieve bestand door met key file als form-data.

Hieronder een voorbeeld in curl:

curl --location 'https://gateway-cmsapi.v2.zabun.be/api/v1/contact/{contact_autoid}/files'
\--header 'X-CLIENT-ID: #X-CLIENT-ID#'
\--header 'CLIENT_ID:   #client_id#'
\--header 'SERVER_ID:   #server_id#'
\--header 'API_KEY:     #api_key#'
\--header 'Content-Type: application/json'
\--form 'file=@"/C:/Uw/Mappen/Folder/bestand_naam.extensie"'

Bij het gebruik van uw eigen client in een programmeertaal, zal u het bestand uiteraard moeten toevoegen aan de request volgens de standaarden van de gekozen taal (bijvoorbeeld een multipart/form-data request en het gebruik van een filestream).

Aanmaken van een nieuwe custom contact zonder taak of andere relaties

Deze endpoint maakt enkel het contact aan, dus geen taak of conversatie, en verstuurt geen mail.

curl --location --request POST 'https://gateway-cmsapi.v2.zabun.be/api/v1/contact' \
--header 'Content-Type: application/json' \
--header 'X-CLIENT-ID: #X-CLIENT-ID#' \
--header 'client_id: #client_id#' \
--header 'server_id: #server_id#' \
--header 'api_key: #api_key#' \
--data '{
"title_id": 1,
"status_id": 1,
"responsible_salesrep_person_id": #person_id#,
"last_name": "Jansens"
}'

Deze payload toont enkel de verplichte velden; zie swagger voor de volledige payload.

Ook nuttig zijn:

Een handige query parameter is check_exists. Indien deze true is, dan wordt er gecontroleerd of het contact al bestaat op basis van de opgegeven data en de contacten die al in uw Zabun bestaan. Standaard is dit false, waardoor er altijd een nieuw contact wordt aangemaakt.

Opzoeken van contacten

Deze endpoint is niet beschikbaar bij het gewone webbouwer profiel.

curl --location --request POST 'https://gateway-cmsapi.v2.zabun.be/api/v1/contact/search' \
--header 'X-CLIENT-ID: #X-CLIENT-ID#' \
--header 'client_id: #client_id#' \
--header 'server_id: #server_id#' \
--header 'api_key: #api_key#' \
--data-raw   ''

Accounts

Accounts zijn een verzameling van contacten die samenhoren en onder één noemer gekoppeld zijn. Accounts kunnen ook op zichzelf gebruikt worden voor een familie, koppel... zonder er contacten aan te koppelen.

Opzoeken van accounts

Deze endpoint is niet beschikbaar bij het gewone webbouwer profiel.

curl --location --request POST 'https://gateway-cmsapi.v2.zabun.be/api/v1/account/search' \
--header 'X-CLIENT-ID: #X-CLIENT-ID#' \
--header 'client_id: #client_id#' \
--header 'server_id: #server_id#' \
--header 'api_key: #api_key#' \
--data-raw   ''

Live Agenda

Met de Live Agenda kan een bezoeker van uw website zelf een bezoekmoment (kijkmoment) voor een pand reserveren. De vertegenwoordiger zet in Zabun bezoekdagen met tijdsloten open; via de API haalt u die sloten op, schrijft u een contact in, en kan dat contact zijn afspraak nadien ook weer annuleren.

De Live Agenda-endpoints vallen onder een apart permissieprofiel, een kleine uitbreiding op het Webbouwer-profiel. Neem hiervoor contact op met de support. Krijgt u een 403 (Verboden), dan is dit profiel nog niet geactiveerd voor uw client_id.

Stap 1: De bezoekmomenten van een pand ophalen

Via GET /liveagenda/{propertyid} krijgt u de geplande bezoekmomenten (sessies) voor een pand.

curl --location --request GET 'https://gateway-cmsapi.v2.zabun.be/api/v1/liveagenda/4129931' \
--header 'X-CLIENT-ID: #X-CLIENT-ID#' \
--header 'client_id: #client_id#' \
--header 'server_id: #server_id#' \
--header 'api_key: #api_key#'

Elke sessie bevat onder andere:

Stap 2: Een contact aanmaken

Om iemand in te schrijven hebt u eerst een contact_autoid nodig. Maak het contact aan via POST /liveagenda/{propertyautoid}/contact. Deze endpoint maakt een contact aan (met als bron "Website"), koppelt er een webtaak op het pand aan, en geeft het contact_autoid terug als antwoord.

curl --location --request POST 'https://gateway-cmsapi.v2.zabun.be/api/v1/liveagenda/4129931/contact' \
--header 'Content-Type: application/json' \
--header 'X-CLIENT-ID: #X-CLIENT-ID#' \
--header 'client_id: #client_id#' \
--header 'server_id: #server_id#' \
--header 'api_key: #api_key#' \
--data '{
    "last_name": "Jansens",
    "first_name": "Jan",
    "email": "[email protected]",
    "language": "NL",
    "mailing_opt_in": true, //Mag contact gemaild worden (marriage), laat dit aanvinken door het contact (niet automatisch!)
    "marketing_opt_in": true //Privacybeleid, laat dit aanvinken door het contact (niet automatisch!)
}'

Stap 3: Het contact inschrijven op een tijdslot

Schrijf het contact in op een slot via POST /liveagenda/{propertyautoid}/registration. In de body geeft u het gekozen slot mee:

Geef daarnaast de header cancelUrl mee met de URL naar uw eigen annulatiepagina, met daarin de placeholder $GUID$. Die placeholder wordt vervangen door de registratie-GUID, die uw bezoeker nodig heeft om te annuleren (zie stap 4). Optioneel kan u ook $PROPERTY_AUTOID$ in de URL opnemen; voor bijkomende parameters kan u support contacteren.

curl --location --request POST 'https://gateway-cmsapi.v2.zabun.be/api/v1/liveagenda/4129931/registration' \
--header 'Content-Type: application/json' \
--header 'X-CLIENT-ID: #X-CLIENT-ID#' \
--header 'client_id: #client_id#' \
--header 'server_id: #server_id#' \
--header 'api_key: #api_key#' \
--header 'cancelUrl: https://uw-website.be/annuleren?guid=$GUID$' \
--data '{
    "task_autoid": 3746002791000009999,
    "session_startdate": "2024-06-01T14:00:00+02:00",
    "contact_autoid": 3709002791000000010
}'

Als antwoord krijgt u de registratie-GUID. Bewaar deze; u hebt hem nodig om de afspraak op te vragen of te annuleren.

Stap 4: Een registratie opvragen of annuleren

Taken

Bij het updaten van de vertegenwoordiger van een taak moet u opletten voor de nieuwe task_autoid. Er wordt namelijk een nieuwe taak met een nieuwe task_autoid gegenereerd, waarbij de oude taak met de meegegeven task_autoid in de patch-URL verwijderd wordt. Dit is uitzonderlijke logica die enkel bij taken en voor het veld responsible_salesrep_person_id uitgevoerd wordt. Andere velden patchen verandert de task_autoid niet.

Zoekfiches

Opzoeken van zoekfiches

curl --location --request POST 'https://gateway-cmsapi.v2.zabun.be/api/v1/request/search' \
--header 'X-CLIENT-ID: #X-CLIENT-ID#' \
--header 'client_id: #client_id#' \
--header 'server_id: #server_id#' \
--header 'api_key: #api_key#' \
--data-raw   ''

Toevoegen van een gemeente aan een zoekfiche-verzoek?

Om een zoekfiche aan te maken, kan u een lijst van city_ids meegeven. Als u een postcode hebt, dan zal u deze moeten vertalen naar een city_id. Dat kan u door eerst onderstaande request te doen (country_geo_ids = id van land, België is de standaard waarde = 23), en dan kan u in zip_codes een lijst van postcodes zetten.

curl --location --request POST 'https://gateway-cmsapi.v2.zabun.be/api/v1/geo/cities/search' \
--header 'X-CLIENT-ID: #X-CLIENT-ID#' \
--header 'Client_ID: #client_id#' \
--header 'Server_ID: #server_id#' \
--header 'API_Key: #api_key#' \
--header 'Content-Type: application/json' \
--data-raw   '{ filtering: {
      "zip_codes": [ 3800, 3840 ],
        "country_geo_ids": [23],
            },
            "paging": {
                "page": 0,
                "size": 10
            },
            "sorting": {
                "order": "ASC"
            },
            }'

En dan kan u via onderstaande call de fiche zelf aanmaken.

curl --location --request POST 'https://gateway-cmsapi.v2.zabun.be/api/v1/contactrequest' \
--header 'Content-Type: application/json' \
--header 'X-CLIENT-ID: #X-CLIENT-ID#' \
--header 'client_id: #client_id#' \
--header 'server_id: #server_id#' \
--header 'api_key: #api_key#' \
--data '{
    "contact": {
        "last_name": "Jansens",
        "title": 1,
    },
    "request": {
        "price": {
            "min" : 250000,
            "max" : 750000
        },
        "sales_rep": #person_id#,
        "cities": [
           #city_ids#
         ],

   }
}'

Dan heeft u een lijst van gemeenten en deelgemeenten, die moet u doorgeven aan de contactrequest API-functie.

Verschil tussen hoofdtypes en types

Zoekfiches in Zabun worden opgeslagen op basis van pandtypes. Wanneer u in Zabun een hoofdtype selecteert, worden automatisch alle onderliggende types van dat hoofdtype aan de zoekfiche toegevoegd. Dezelfde logica geldt wanneer u een zoekfiche via de API aanmaakt.

Bij het aanmaken van een zoekfiche kunt u zowel een lijst met hoofdtypes (headtypes) als een lijst met types (types) doorgeven:

Wanneer u een specifiek type toevoegt via types, zal het bijbehorende hoofdtype wel zichtbaar zijn in de zoekfiche binnen Zabun. Dit komt omdat het geselecteerde type onder dat hoofdtype valt. Het hoofdtype zelf wordt niet opgeslagen als selectie; enkel het gekozen type wordt bewaard.

Enkel bepaalde types van een hoofdtype selecteren
Wilt u slechts één of enkele types van een bepaald hoofdtype toevoegen, zonder alle types van dat hoofdtype te selecteren? Voeg dan uitsluitend de gewenste type_id-waarden toe aan types en laat headtypes leeg.

Voorbeeld:

{  
 "headtypes": [],  
 "types": [12, 15]   //appartement (Appartement) en penthouse (Huis)
}

Hoofdtypes en types combineren
U kunt beide lijsten ook combineren. Zo kunt u bijvoorbeeld alle huistypes toevoegen via een headtype_id, en daarnaast één specifiek type "grond" toevoegen.

Voorbeeld:

{ 
 "headtypes": [3], // Huis
 "types": [24]    //bouwgrond (Grond)
}

Hierdoor worden:

Op die manier kunt u een zoekfiche zeer gericht samenstellen, zonder automatisch alle types van elk hoofdtype te moeten opnemen.

curl --location --request POST 'https://gateway-cmsapi.v2.zabun.be/api/v1/contactrequest' \
--header 'Content-Type: application/json' \
--header 'X-CLIENT-ID: #X-CLIENT-ID#' \
--header 'client_id: #client_id#' \
--header 'server_id: #server_id#' \
--header 'api_key: #api_key#' \
--data '{
    "contact": {
        "last_name": "Jansens",
        "title": 1,
    },
    "request": {
        "price": {
            "min" : 250000,
            "max" : 750000
        },
        "sales_rep": #person_id#,
        "cities": [
           #city_ids#
         ],
        "headtypes": [3], //Huis = alle types onder hoofdtype Huis
        "types": [19] //Landbouwgrond. Hoofdtype grond zal zichtbaar zijn in de zoekfiche, met enkel landbouwgrond aangevinkt
   }
}'

Toevoegen van extra filters op de zoekfiche

Mits de nodige permissies is het mogelijk om een zoekfiche aan te passen en extra filters/parameters toe te voegen, zodat de gevonden panden gerichter gezocht kunnen worden voor het contact. Hieronder een voorbeeld van hoe u een indelingsfilter kan toevoegen op een zoekfiche die gemaakt is via de basis /contactrequest endpoint. Zoekfiches via de API aanpassen is redelijk complex. U kan support aanvragen om een voorbeeld request te laten aanmaken als u een specifiek scenario wilt toepassen.

PreSetup

  1. Via GET /request/option_items (het parameters object), of GET /request/parameters, kunnen alle mogelijke filters voor een zoekfiche opgehaald worden. In geval van indeling zoekt u naar de objecten met type: LAYOUT. Deze hebben allemaal ID = 13. U kan ook enkel de layout-parameterfilters ophalen via GET /request/parameters?parameter_id=13. Voor de PATCH request hebben we de autoid van deze objecten nodig. Het is hier van belang dat u bijhoudt welke hoofdtypes u doorgegeven hebt bij de creatie van de zoekfiche, aangezien de indelingsfilters bestaan op basis van hoofdtype, en u deze head_type_ids nodig zal hebben om de correcte autoids te verkrijgen. Hoofdtypes van panden vindt u via GET /property/head_types. Voorbeeld:
  1. De beschikbare indelingen voor uw bedrijf vindt u via GET /property/layouts. De "ID" is hiervan van belang.

Zoekfiche aanmaken en aanpassen voor layout

  1. Maak een basiscontact + zoekfiche aan via de /contactrequest. Als resultaat krijgt u de request_autoid.
  2. Om de zoekfiche aan te passen, gebruikt u /request/{request_autoid} (met de request_autoid uit puntje 1).
  3. In de body vult u de volgende variabele aan om de indelingsfilters aan te passen:
{"detail_layouts": [{hier komen de layout-objecten waarvoor u de filter wil toevoegen aan de zoekfiche}]}
  1. Per layout en per hoofdtype moet u hier een layout-filterobject toevoegen. Het object ziet er als volgt uit:
{"count": x,  = aantal van deze indeling waarvoor gezocht wordt = exact nummer (geen min-max)
 "layout_Id": y, = ID te vinden in /property/layouts
 "parameter_autoid": z = autoid te vinden in /request/parameters
}

Bijvoorbeeld:

{"detail_layouts": [
   {"count": 1,
    "layout_Id": 11, //zolder
    "parameter_autoid": 98 //autoid van layout parameter voor huis
   },
   {
    "count": 2,
    "layout_Id": 3, //kelder
    "parameter_autoid": 97 //autoid van layout parameter voor appartement
   },
   {
    "count": 3,
    "layout_Id": 14, //parkeerplaats
    "parameter_autoid": 97 //autoid van layout parameter voor appartement
   },
   {
    "count": 1,
    "layout_Id": 14, //parkeerplaats
    "parameter_autoid": 101 //autoid van layout parameter voor vakantiewoning, waarvan de head_type_id = 7
   }
 ]
}
  1. Gelieve geen andere objecten mee te geven, zoals detail_min_max, price_min, description... of andere variabelen, aangezien deze ook gewijzigd zullen worden door de patch als ze meegegeven zijn. Ze worden genegeerd als ze niet in de body staan. Indien u niet anders kan dan ze meegeven (door een generated client bijvoorbeeld), vult u ze best volledig in zoals ze nu al waren. Hiervoor haalt u de zoekfiche best nog eens apart op via GET /request/{request_autoid}, waarvoor u de nodige permissie zal nodig hebben.

Keuzelijsten

Alle keuzelijsten hebben hun eigen endpoints, maar u kan ook alle keuzelijsten voor een sectie in één keer ophalen via de /option_items endpoint.

Voorbeeld: GET /property/option_items.

Met deze endpoint kan u het aantal requests naar de API verminderen.

Extra Velden

Het ophalen en invullen van extra velden op pand-, contact- of accountniveau kan op verschillende manieren. Hieronder een stappenplan met een contact-dropdown extra veld als voorbeeld. De extra veld endpoints zijn complex en mogelijk niet volledig operationeel. Contacteer support indien u hulp nodig hebt.

Stap 1: Ophalen van extra velden

De "extra_fields" endpoints halen de mogelijke extra velden op voor hun respectievelijke object: GET /property/extra_fields, GET /contact/extra_fields, GET /account/extra_fields, of GET /extra_fields voor ze allemaal.

curl --location 'https://gateway-cmsapi.v2.zabun.be/api/v1/contact/extra_fields' \
--header 'X-CLIENT-ID: #X-CLIENT-ID#' \
--header 'client_id: #client_id#' \
--header 'server_id: #server_id#' \
--header 'api_key: #api_key#' \
--header 'Content-Type: application/json'



Stap 1 bis: Ophalen van dropdown-opties

Er zijn drie mogelijkheden om de optielijst op te halen van een extra veld met type "DROPDOWNLIST":

  1. U kan de /extra_fields endpoint extenden om de lijst als extra data binnen te krijgen. Dit zorgt ervoor dat de request mogelijk wat langer duurt.
curl --location 'https://gateway-cmsapi.v2.zabun.be/api/v1/contact/extra_fields?extended=true' \
--header 'X-CLIENT-ID: #X-CLIENT-ID#' \
--header 'client_id: #client_id#' \
--header 'server_id: #server_id#' \
--header 'api_key: #api_key#' \
--header 'Content-Type: application/json'



https://gateway-cmsapi.v2.zabun.be/api/v1/extra_fields?extended=true haalt dan alle extra velden op met hun dropdown-opties.

  1. Via de volgende endpoint kan u de dropdown-opties apart ophalen per extra veld:
curl --location 'https://gateway-cmsapi.v2.zabun.be/api/v1/extra_fields/3523002791000000004/dropdowns \
--header 'X-CLIENT-ID: #X-CLIENT-ID#' \
--header 'client_id: #client_id#' \
--header 'server_id: #server_id#' \
--header 'api_key: #api_key#' \
--header 'Content-Type: application/json'



  1. U kan ook via https://gateway-cmsapi.v2.zabun.be/api/v1/extra_fields/dropdowns alle dropdown-opties ophalen voor alle extra velden. Het resultaat is hetzelfde als hierboven. U moet zelf de dropdown-opties groeperen op basis van de extra_field variabele.

Stap 2. Ophalen van de extra-veldwaardes die ingevuld zijn bij het object

Dit kan via de /extra_field_values endpoints bij de respectievelijke controllers.

//Het grote nummer in de URL is een contact_autoid
curl --location 'https://gateway-cmsapi.v2.zabun.be/api/v1/contact/3709002791000000010/extra_field_values 
--header 'X-CLIENT-ID: #X-CLIENT-ID#' \
--header 'client_id: #client_id#' \
--header 'server_id: #server_id#' \
--header 'api_key: #api_key#' \
--header 'Content-Type: application/json'



Voor het ophalen van de waarde gebruikt u ofwel de respectievelijke value_xxxx, of de generieke value variabele. In het voorbeeld is het type "DROPDOWNLIST" en kan u value_ddl gebruiken, maar ook value, die dezelfde waarde heeft.

Hieronder een lijst van de koppeling tussen type en waarde:

Stap 3. Invullen of aanpassen van een extra-veldwaarde

  1. Dit kan via de PUT .../extra_field_values endpoints bij de respectievelijke controllers. De belangrijke velden in de body zijn extra_field_autoid en value_xxxx:
curl --location --request PUT 'https://gateway-cmsapi.v2.zabun.be/api/v1/contact/3709002791000000010/extra_field_value' \
--header 'X-CLIENT-ID: #X-CLIENT-ID#' \
--header 'client_id: #client_id#' \
--header 'server_id: #server_id#' \
--header 'api_key: #api_key#' \
--header 'Content-Type: application/json'
--data '{
    "extra_field_autoid": 3523002791000000004,
    "value_ddl": 5
}'

U hoeft geen object_key_autoid in te vullen. Indien u dit toch wilt doen, moet u zorgen dat deze gelijk is aan de ID die u gebruikt in de URL van de endpoint. In het voorbeeld moet object_key_autoid = 3709002791000000010.

Op dit moment kan u de generieke value + type variabele niet gebruiken om de waarde in te vullen; u moet de specifieke gebruiken. De volgende waarden werken, maar zijn nog niet uitvoerig getest. Indien u een van deze wilt gebruiken, neem contact op met de support zodat uw gevraagde waarde afgecheckt kan worden, of gebruik het op eigen risico:

  1. U kan ook via de extra_field controller een waarde invullen voor een extra veld van eender welk object. Bij deze endpoint moet u wél de object_key_autoid variabele invullen met de id van het pand, het contact of het account. De validatie controleert of deze bestaat.
curl --location --request PUT 'https://gateway-cmsapi.v2.zabun.be/api/v1/extra_field/extra_field_value' \
--header 'X-CLIENT-ID: #X-CLIENT-ID#' \
--header 'client_id: #client_id#' \
--header 'server_id: #server_id#' \
--header 'api_key: #api_key#' \
--header 'Content-Type: application/json'
--data '{
    "extra_field_autoid": 3523002791000000004,
    "object_key_autoid": 3709002791000000010,
    "value_ddl": 5
}'

Vertegenwoordigers

Een vertegenwoordiger — ook wel "sales rep", "makelaar", "gebruiker" of person genoemd — is de persoon binnen uw bedrijf die aan panden, contacten, taken, zoekfiches en andere data gekoppeld wordt. In de API is dit steeds een person, geïdentificeerd door de variabele person_id. Deze person_id is dezelfde waarde die u in velden als responsible_salesrep_person_id, creation_person_id, ... en sales_rep gebruikt. Dit is vaak uw eigen gebruiker-id (X-USER-ID), maar kan ook een collega of medewerker van het kantoor zijn.

U haalt de vertegenwoordigers op via GET /person. Dit is vooral handig voor de naam en eventueel een foto. Het is aangeraden om deze data op te slaan of te cachen.

curl --location --request GET 'https://gateway-cmsapi.v2.zabun.be/api/v1/person' \
--header 'X-CLIENT-ID: #X-CLIENT-ID#' \
--header 'client_id: #client_id#' \
--header 'server_id: #server_id#' \
--header 'api_key: #api_key#' \

Let op: een account is niet hetzelfde als een gebruiker/vertegenwoordiger. Accounts zijn een apart soort relatie in Zabun. Om aan uw vertegenwoordigers te raken, hebt u dus geen rechten op accounts nodig — gebruik gewoon GET /person.

Kantoren

Een kantoor (office) is een vestiging van uw bedrijf. Panden, contacten en taken kunnen aan een kantoor gekoppeld worden via het veld office_autoid (zie bijvoorbeeld "Aanmaken van een nieuw pand"). De waarde 0 verwijst naar het hoofdkantoor.

Deze data is enkel nuttig als uw bedrijf met meerdere kantoren werkt, bijvoorbeeld om per pand het juiste kantoor met adres en logo te tonen. Cache deze data; kantoren veranderen zelden.

U haalt de lijst van kantoren op via GET /office. Per kantoor krijgt u een samenvatting met onder andere office_autoid, name, default_user_person_id, logo_url, ...

curl --location --request GET 'https://gateway-cmsapi.v2.zabun.be/api/v1/office' \
--header 'X-CLIENT-ID: #X-CLIENT-ID#' \
--header 'client_id: #client_id#' \
--header 'server_id: #server_id#' \
--header 'api_key: #api_key#'

De volledige gegevens van één kantoor haalt u op via GET /office/{office_autoid}. Naast de samenvatting krijgt u hier ook het gekoppelde account-object met de adres- en contactgegevens van het kantoor. Voeg ?extended=true toe voor de uitgebreide accountdata.

Korte vragen met bondige antwoorden

Q: Mogen panden 'on the fly' opgevraagd worden? Of is het de bedoeling dat alle data opgehaald wordt in een eigen databank?

A: Panden kunnen 'on the fly' opgehaald worden, maar we raden dit ten strengste af om de volgende redenen:

  1. De API is ingesteld met een rate-limit, waardoor u maar een beperkt aantal requests kan uitsturen per minuut. Indien u veel verkeer ontvangt op uw website, kan dit betekenen dat u dit limit bereikt en tijdelijk geen requests meer mag uitsturen.
  2. Indien er een fout ontstaat op onze API of deze gaat offline, bijvoorbeeld door een update of interne problemen, dan hebt u tijdelijk geen data meer en zullen de panden niet meer zichtbaar zijn op uw website.
  3. De snelheid van uw website wordt bepaald door de snelheid van de requests naar de API. Indien er netwerkproblemen zijn of onze API vertraging heeft tijdens piekmomenten, zal dit direct zichtbaar zijn op uw website. U voorziet ofwel een database, ofwel ten minste een cache die de panddata bijhoudt. Zowel de "Property Search" als de "Property Media Sync" (en de delta) accepteren een updated_since/last_changed_date filter om de laatst gewijzigde panden op te halen.

Dit is ook van toepassing op de foto's en bestanden van het pand.

Q: Ik krijg een validatie error met als melding "Error converting value xxxx to type 'System.Int64[]'".

A: U stuurt een waarde, zoals een id, apart door terwijl de variabele/filter een lijst verwacht. Zet het ID tussen []. Bijvoorbeeld office_autoids: [xxxxxxxxxx] (foutief: "office_autoids": xxxxxxxxx).

Q: Ik heb bv. 15 records in Zabun maar zie er maar bv. 5 in de api response?

A: Kijk de paging parameters na in uw search body. Dit voorbeeld komt voor als u een page size van 10 hebt en de data van page 1 opvraagt. Start dus altijd met index 0 en loop door de pages heen tot u geen data meer krijgt, of bereken het aantal nodige pages op basis van de total count. Zie "Sorteren, filteren en paging van data".

Q: Indien een pand wordt toegevoegd aan een project, wordt de gewijzigd-datum van het project aangepast?

A: Ja.

Q: Wat is het nut van de sales_rep variabele (=vertegenwoordiger/makelaar) in een zoekfiche en wat gebeurt er als deze niet is ingevuld bij de request?

A: De sales_rep bij een zoekfiche is handig als u een specifieke vertegenwoordiger hebt die binnenkomende zoekfiches behandelt, of als men met regio's werkt. Het is niet verplicht, maar betekent wel dat de zoekfiche in Zabun terechtkomt zonder vertegenwoordiger. Die kan uiteraard in Zabun of via de API alsnog ingevuld worden via een update.

Q: Moeten bestanden en foto's (=Media) gedownload worden en mogen de directe URL gebruikt worden?

A: Wij raden ten sterkste aan om kopieën te maken van de publieke foto's en bestanden die weergegeven moeten worden bij het pand op uw website. U mag de directe URLs gebruiken. Echter, als de makelaar de foto/het bestand verwijdert uit Zabun, of wij een aanpassing doen aan ons bestandensysteem, dan zal de foto/het bestand niet meer zichtbaar zijn (indien deze ook uit de cache verdwenen is) en is dit direct zichtbaar op uw website, waardoor er panden zonder foto's kunnen verschijnen. U kan dit verhelpen door de data opnieuw op te halen en de geldige urls te verkrijgen.