W jaki sposób podłączyć stronę WWW do voxCRM?

System voxCRM udostępnia publiczne API XML (z opcją JSON), dzięki któremu strona WWW może w pełni zautomatyzowany sposób pobierać aktualne dane o inwestycjach, dostępnych lokalach oraz historii zmian cen. Dane w pliku XML są automatycznie aktualizowane raz na godzinę — rekomendujemy buforowanie po stronie WWW.

Spis treści

1. Endpoint — Lista inwestycji
2. Endpoint — Lista lokali dla inwestycji
3. Endpoint — Historia zmian cen
4. Słowniki: statusy, typy lokali i kierunki świata
5. Przykłady integracji
6. Kontakt

1. Endpoint — Lista inwestycji

URL (XML — format domyślny):

GET https://demo1.voxdeveloper.com/webservice/investments-list/api_key/{API_KEY}

Przykład dla instancji demo (XML):
https://demo1.voxdeveloper.com/webservice/investments-list/api_key/32323df398b32e65b22a9aae083c6751ec9c5e99

Wersja JSON — ten sam endpoint zwraca dane w formacie JSON po dodaniu segmentu /json/1 w adresie:

GET https://demo1.voxdeveloper.com/webservice/investments-list/api_key/{API_KEY}/json/1

Przykład dla instancji demo (JSON):
https://demo1.voxdeveloper.com/webservice/investments-list/api_key/32323df398b32e65b22a9aae083c6751ec9c5e99/json/1

Pola domyślne (zawsze zwracane)

Tagi są dodawane do każdego elementu <investment>, ale mogą mieć pustą wartość, jeśli dane nie zostały uzupełnione w CRM.

Pola opcjonalne (zależne od ustawień)

Te pola pojawią się w XML po włączeniu odpowiedniej opcji przez administratora, pod warunkiem że istnieją odpowiednie zdjęcia, logo lub dokumenty. Jeśli chcesz wykorzystać któreś z nich, poproś administratora o włączenie.

Przykład XML

<?xml version="1.0"?>
<xml>
  <investment>
    <id>123</id>
    <name>Testowa Inwestycja</name>
    <voivodeship>mazowieckie</voivodeship>
    <address_district>Śródmieście</address_district>
    <address_street>Al. Jerozolimskie</address_street>
    <address_building_number>65</address_building_number>
    <address_apartment_number></address_apartment_number>
    <postal_code>00-001</postal_code>
    <latitude>52.2297</latitude>
    <longitude>21.0122</longitude>
    <city>Warszawa</city>
    <transfer_ownership_date>2025-06-30</transfer_ownership_date>
    <website_url>https://inwestycja.pl</website_url>
    <monetary_benefits>Opłaty eksploatacyjne</monetary_benefits>
    <status>W sprzedaży</status>
    <investment_logo>https://demo1.voxdeveloper.com/files/investments/logo.png</investment_logo>
  </investment>
</xml>

2. Endpoint — Lista lokali dla inwestycji

URL (XML — format domyślny):

GET https://demo1.voxdeveloper.com/webservice/realestatestatuslist/api_key/{API_KEY}/investment_id/{ID}

Przykład dla instancji demo, XML (inwestycja nr 120):
https://demo1.voxdeveloper.com/webservice/realestatestatuslist/api_key/32323df398b32e65b22a9aae083c6751ec9c5e99/investment_id/120

Wersja JSON — ten sam endpoint zwraca dane w formacie JSON po dodaniu segmentu /json/1 w adresie:

GET https://demo1.voxdeveloper.com/webservice/realestatestatuslist/api_key/{API_KEY}/json/1/investment_id/{ID}

Przykład dla instancji demo, JSON (inwestycja nr 120):
https://demo1.voxdeveloper.com/webservice/realestatestatuslist/api_key/32323df398b32e65b22a9aae083c6751ec9c5e99/json/1/investment_id/120

Filtrowanie wyników w URL

Endpoint realestatestatuslist wspiera dodatkowe, opcjonalne filtry przekazywane w adresie URL. Pozwalają one ograniczyć rozmiar zwracanego pliku XML — przydatne przy dużych inwestycjach, gdzie pełna lista lokali ładuje się wolno.

Zasady łączenia filtrów:

• Jako pierwszy w adresie występuje investment_id lub stage_id.
• Następnie, w dowolnej kolejności, można dodać type_id i/lub status_id.
• Każdy z filtrów type_id i status_id przyjmuje pojedynczą wartość lub listę rozdzieloną przecinkami (CSV).

Przykłady poprawnych adresów:

# Tylko mieszkania (typ 1) w inwestycji 120
.../realestatestatuslist/api_key/{API_KEY}/investment_id/120/type_id/1
# Mieszkania i garaże (typy 1 i 2)
.../realestatestatuslist/api_key/{API_KEY}/investment_id/120/type_id/1,2
# Tylko lokale dostępne (status 1)
.../realestatestatuslist/api_key/{API_KEY}/investment_id/120/status_id/1
# Mieszkania dostępne i z rezerwacją ustną (typ 1, statusy 1 i 2)
.../realestatestatuslist/api_key/{API_KEY}/investment_id/120/type_id/1/status_id/1,2
# Filtrowanie po etapie zamiast inwestycji
.../realestatestatuslist/api_key/{API_KEY}/stage_id/15/type_id/1,2/status_id/1

Pola domyślne (zawsze zwracane)

Poniższe 26 tagów jest dodawanych do każdego elementu <realestate>. „Zawsze zwracane” oznacza obecność tagu, a nie gwarancję niepustej wartości: jeśli dane nie zostały uzupełnione, tag może być pusty. Puste pole liczbowe nie oznacza zera.

Pola podstawowe zwracane warunkowo

Pola cenowe (warunkowe)

Zwracane dla lokali ze statusami 1 i 2 lub po włączeniu opcji „Dodaj ceny do xml kiedy status jest niedostępny”. Przy wyłączonym eksporcie ceny danego lokalu pola price, promotion_price, promotion_price_net i daty promocji pozostają puste, a pola pricemkw, price_net i pricemkw_net nie są dodawane. Pola cen i dat promocji są uzupełniane tylko wtedy, gdy promocja jest dostępna w danym dniu; daty mogą pozostać puste, jeśli nie określono jej początku lub końca.

Pola opcjonalne

Widoczność poniższych pól zależy od konfiguracji, uzupełnienia danych lub obecności plików. Pola balkon, taras, ogrod, loggia i area_attic są dodawane przy niepustej, niezerowej wartości atrybutu. Pola www_id, balcony_count i sales_area wymagają włączenia także odpowiedniego pola dodatkowego lokalu w CRM. Plany, karty i miniatury są dodawane, gdy istnieją odpowiednie pliki; warianty _extension wymagają dodatkowego ustawienia eksportu linków z rozszerzeniem. Tag może mieć pustą wartość, jeśli dane nie zostały uzupełnione.

Dodatkowe ceny:

Wynajem:

Powierzchnie i miary:

Identyfikatory i nazewnictwo:

Cechy i wyposażenie:

Parkingi, piwnice, rowerownie:

Energetyka:

Daty i statusy dodatkowe:

Pliki:

Struktury zagnieżdżone

Pojawiają się jako osobne elementy wewnątrz <realestate>.

<contiguity_list> — powiązane lokale / przynależności. Lista jest dodawana do każdego lokalu i może być pusta. Poszczególne pola <contiguity> są zwracane według warunków podanych poniżej:

<storey_list> — rozbicie powierzchni na kondygnacje / strefy dodatkowe. Lista kondygnacji i stref lokalu, które nie są głównymi pomieszczeniami (np. antresole, strychy, poddasza). Sekcja pojawia się po włączeniu opcji „Powierzchnia apartamentu" (wspólnej dla <storey_list> i <room_list>). Każdy <storey> zawiera:

<room_list> — rozbicie powierzchni na pomieszczenia główne. Lista pomieszczeń głównych lokalu (np. pokoje, kuchnia, łazienka). Sekcja pojawia się po włączeniu opcji „Powierzchnia apartamentu" (wspólnej z <storey_list>). Każdy <room> zawiera:

<flags_list> — atuty / wyróżniki lokalu. Lista cech wyróżniających lokal (np. „Balkon", „Narożne okno", „Widok na park"). Sekcja pojawia się po włączeniu opcji „Zalety". Każdy <flag> zawiera:

Przykład XML

<?xml version="1.0"?>
<xml>
  <realestate>
    <id>2041</id>
    <investment_id>15</investment_id>
    <investment_name>Testowa Inwestycja</investment_name>
    <investment_status>W sprzedaży</investment_status>
    <investment_stage>6</investment_stage>
    <stage>Etap I</stage>
    <building>A</building>
    <name>A - M1</name>
    <local_number>M1</local_number>
    <status_id>1</status_id>
    <status_name>Dostępne</status_name>
    <area>45.50</area>
    <area_usable>38.20</area_usable>
    <rooms>2</rooms>
    <floor>3</floor>
    <completion_date>2025-06-15</completion_date>
    <ask_for_price>0</ask_for_price>
    <city>Warszawa</city>
    <price>490000.00</price>
    <pricemkw>10769.23</pricemkw>
    <price_net>453703.70</price_net>
    <pricemkw_net>9971.51</pricemkw_net>
    <date_modified>2025-05-26 17:00:00</date_modified>
    <type_id>1</type_id>
    <type>Mieszkanie</type>
    <balkon>8.50</balkon>
    <plan_link>https://demo1.voxdeveloper.com/files/realestate/plan.pdf</plan_link>
    <card_link>https://demo1.voxdeveloper.com/files/realestate/card.pdf</card_link>
    <contiguity_list>
      <contiguity>
        <contiguity_name>MP-12</contiguity_name>
        <contiguity_type>Miejsce postojowe</contiguity_type>
        <contiguity_price>25000.00</contiguity_price>
        <contiguity_area>12.00</contiguity_area>
      </contiguity>
    </contiguity_list>
  </realestate>
</xml>

3. Endpoint — Historia zmian cen

Link do pliku XML historii cen każdego lokalu znajdziesz w polu price_change_history poprzedniego endpointu. Przykład ścieżki:

https://demo1.voxdeveloper.com/files/price_changes/{hash1}/{hash2}.xml

Plik jest generowany automatycznie po każdej zmianie cen — nie wymaga autoryzacji poza znajomością URL-a. Dla wygody dostępna jest również wersja JSON (jeśli administrator ją włączył).

Pola podstawowe

Poniższe tagi są dodawane do elementu <realestate>, z wyjątkiem warunkowych type_id i type. Wartości mogą być puste, jeśli dane nie zostały uzupełnione.

Pola opcjonalne (włączane przez administratora)

Struktura <price_history>

Zawiera listę <price_change>. Każdy zawiera:

Format JSON historii: price_history jest tablicą wpisów. Każdy wpis zawiera date_modified, before i after; obecny generator JSON nie dodaje pola rodzaju zmiany type we wpisie historii. Ceny są liczbami, a brakujące lub puste wartości cenowe z XML są konwertowane na 0 — taka wartość nie musi oznaczać ceny równej zero.

Przykład XML

<?xml version="1.0"?>
<xml>
  <realestate>
    <id>2041</id>
    <investment_id>15</investment_id>
    <investment_name>Testowa Inwestycja</investment_name>
    <investment_stage>6</investment_stage>
    <building>A</building>
    <name>A - M1</name>
    <local_number>M1</local_number>
    <type_id>1</type_id>
    <type>Mieszkanie</type>
    <price>490000.00</price>
    <price_net>453703.70</price_net>
    <pricemkw>10769.23</pricemkw>
    <pricemkw_net>9971.51</pricemkw_net>
    <price_history>
      <price_change>
        <date_modified>2025-05-20 09:00</date_modified>
        <type>Cena katalogowa</type>
        <before/>
        <after>
          <price>500000.00</price>
          <price_net>462962.96</price_net>
          <pricemkw>10989.01</pricemkw>
          <pricemkw_net>10175.01</pricemkw_net>
        </after>
      </price_change>
      <price_change>
        <date_modified>2025-05-26 17:00</date_modified>
        <type>Cena katalogowa</type>
        <before>
          <price>500000.00</price>
          <price_net>462962.96</price_net>
          <pricemkw>10989.01</pricemkw>
          <pricemkw_net>10175.01</pricemkw_net>
        </before>
        <after>
          <price>490000.00</price>
          <price_net>453703.70</price_net>
          <pricemkw>10769.23</pricemkw>
          <pricemkw_net>9971.51</pricemkw_net>
        </after>
      </price_change>
    </price_history>
  </realestate>
</xml>

4. Słowniki: statusy, typy lokali i kierunki świata

Statusy lokali

Typy lokali

Kierunki świata (pole direction)

Pole direction w XML opisuje strony świata, na które wychodzi lokal. Może zawierać jedną lub kilka wartości rozdzielonych przecinkami (dla lokali narożnych / przechodnich).

Format wartości zależy od ustawienia w panelu voxCRM — opcji „Wyświetl alternatywną listę stron świata (skrócone polskie nazwy i posortowane według zegara)":

Pełna lista dostępnych kodów (wariant domyślny — opcja wyłączona)

5. Przykłady integracji

PHP — pobranie statusu lokalu

<?php
// Dla środowiska produkcyjnego podmień adres instancji, klucz API i ID inwestycji na własne.
function getRealEstateInfo(int $id): ?array {
    $url = 'https://demo1.voxdeveloper.com/webservice/realestatestatuslist'
         . '/api_key/32323df398b32e65b22a9aae083c6751ec9c5e99/investment_id/120';
    $xml = simplexml_load_file($url);
    if ($xml === false) {
        return null;
    }
    foreach ($xml->realestate as $realestate) {
        if ((int) $realestate->id === $id) {
            return [
                'id'          => (string) $realestate->id,
                'status_id'   => (int)    $realestate->status_id,
                'status_name' => (string) $realestate->status_name,
                'price'       => (float)  $realestate->price,
                'area'        => (float)  $realestate->area,
            ];
        }
    }
    return null;
}
$info = getRealEstateInfo(4178);
if ($info !== null) {
    echo "Lokal #{$info['id']} — {$info['status_name']} — {$info['price']} PLN";
}

WordPress — shortcode z buforowaniem

<?php
/* Plugin Name: voxCRM Real Estate Table */
function voxcrm_realestate_table() {
    if (false === ($output = get_transient('voxcrm_realestate_table'))) {
        // Dla środowiska produkcyjnego podmień adres instancji, klucz API i ID inwestycji na własne.
        $url = 'https://demo1.voxdeveloper.com/webservice/realestatestatuslist'
             . '/api_key/32323df398b32e65b22a9aae083c6751ec9c5e99/investment_id/120';
        $xml = simplexml_load_file($url);
        if ($xml === false) {
            return '<p>Brak danych.</p>';
        }
        $output = '<table><thead><tr>'
                . '<th>Lokal</th><th>Metraż</th><th>Status</th><th>Cena</th>'
                . '</tr></thead><tbody>';
        foreach ($xml->realestate as $r) {
            $output .= sprintf(
                '<tr><td>%s</td><td>%s m²</td><td>%s</td><td>%s PLN</td></tr>',
                esc_html((string) $r->name),
                esc_html((string) $r->area),
                esc_html((string) $r->status_name),
                esc_html((string) $r->price)
            );
        }
        $output .= '</tbody></table>';
        set_transient('voxcrm_realestate_table', $output, HOUR_IN_SECONDS);
    }
    return $output;
}
add_shortcode('voxcrm_realestate_table', 'voxcrm_realestate_table');

Powiązane materiały

• Jak pobrać dane historii cen lokalu
• Jak zarządzać prospektem informacyjnym do przekazania na dane.gov.pl oraz na stronę WWW

6. Kontakt

W razie pytań lub problemów z integracją prosimy o kontakt z działem wsparcia technicznego:

• E-mail: kontakt@voxcommerce.pl
• Telefon: 534 571 638

W sprawach związanych z kluczem API, zakresem udostępnionych inwestycji oraz widocznością pól opcjonalnych — skontaktuj się z administratorem Twojej instancji voxCRM.