# Špecifikácia importov / exportov pre RealityExport.sk

- 1. Použité skratky
- 2. Import na RealityExport
  - 2.1. Úvod
  - 2.2. Parametre importného skriptu
  - 2.3. Formát XML
    - 2.3.1 Formát agents.xml
      - 2.3.1.1 Popis polí agents.xml
      - 2.3.1.2 Odpovedné XML po spracovaní
    - 2.3.2 Formát objects.xml
      - 2.3.2.1 Popis polí objects.xml
      - 2.3.2.2 Odpovedné XML po spracovaní

## 1. Použité skratky

- RE - RealityExport.sk
- RK - realitná kancelária

## 2. Import na RealityExport

### 2.1. Úvod

Pre export údajov Vašej realitnej kancelárie na RealityExport (ďalej len RE), je potrebné na Vašej strane (servri) pripraviť výstupy vo formáte XML, ktoré budete posielať pomocou metódy POST na URL adresu nášho importného systému.

Keď budú Vaše výstupy pripravené a v poriadku, sprístupníme tento import ako "osobný", teda bude možné ho importovať iba na Váš účet RK (realitnej kancelárie)

### 2.2. Parametre importného skriptu

Importný skript je umiestnený na adrese http://realityexport.sk/import/. Skript očakáva tieto POST parametre:

- user Prihlasovacie meno do RE
- pass Heslo do RE hashované metódou md5
- data XML dáta s maklérmi alebo inzerátmi

Po spracovaní XML dostanete od skriptu odpoveď vo formáte XML o priebehu spracovania. Výstup sa líši podľa toho, či ste poslali XML s maklérmi alebo inzerátmi

Pre testovanie môžete použiť pripravený formulár na adrese http://realityexport.sk/import/test.html. Stačí ak máte pripravené XML výstupy v správnom formáte.

Posielajte nám len dáta, ktoré sa zmenili alebo pridali nové aby sme znížili záťaž nášho aj Vášho servra. V ideálnom prípade bude, ak nám budete posielať zmeny po jednom v priebehu dňa, tak ako sa menia u Vás a tým rozložíme záťaž.

### 2.3. Formát XML

Kódová stránka suboru musí byť UTF-8. XML musí byť validné, aby ho parser vedel spracovať.

#### 2.3.1 Formát agents.xml

    <?xml version="1.0" encoding="UTF-8"?>
    <export>
      <agents>
        <agent>
          <data>
            <portal_id>1</portal_id>
    	<delete>0</delete>
            <meno>Meno maklera</meno>
            <tel1>1111 2222222</tel1>
            <tel2/>
            <mobil1/>
            <mobil2/>
            <fax/>
            <email>makler@vasadomena.sk</email>
          </data>
        </agent>
        <agent>
          ...
        </agent>
        ...
      </agents>
    </export>

##### 2.3.1.1 Popis polí agents.xml

Názov | Typ | Veľk. | Povinný | Popis
--- | --- | --- | --- | ---
portal_id | varchar | 50 | áno | Vaše id makéra - bude využité pri párovaní v našom systéme
delete | varchar | 50 | nie | Príznak, či sa má záznam zmazať. Ak je 1, nemusia sa uviesť žiadne ďalšie polia okrem portal_id
meno | varchar | 100 | áno | Meno + priezvisko vrátane titulov
tel1 | varchar | 50 | áno |
tel2 | varchar | 50 | nie |
mobil1 | varchar | 50 | nie |
mobil2 | varchar | 50 | nie |
fax | varchar | 50 | nie |
email | varchar | 100 | áno |

##### 2.3.1.2 Odpovedné XML po spracovaní

    <?xml version="1.0" encoding="UTF-8"?>
    <response>
      <agent>
        <portal_id>1</portal_id>
        <status>Maklér vytvorený</status>
        <status_code>2</status_code>
      </agent>
      <agent>
       ...
      </agent>
    </response>

Kód stavu (status_code) | Stav (status) | Poznámka
--- | --- | ---
1 | Maklér vytvorený | Pridaný nový maklér
2 | Maklér upravený | Upravený maklér. portal_id sa našlo v našej databáze, tak boli údaje na makléra upravené.
3 | Maklér vymazaný | tag deleted nastavený na 1, maklér sa našiel v našej databáze a vymazal sa
4 | Maklér neexistuje | Snaha o zmazanie makléra, ktorý neexistuje v našej databáze
5 | Chybné alebo chýbajúce povinné údaje: nasleduje zoznam chybných polí | Nevyplnili ste niektoré z povinných polí.

#### 2.3.2 Formát objects.xml

Údaje kazdého inzerátu sú rozdelené na tri časti:

- data - všetky jazykovo nezásvislé, číselné a čiselníkové údaje
- lang_data - jazykovo závislé dáta ako nadpis, text, poznámky. Momentálne RE podporuje len jazyk SK, no špecifikácia už počíta s využitím viacerých jazykov,
- media - všetky obrázky pripojené k inzeátu, v buducnosti možno rózne dokumenty ako prílohy.

Všetky povinné položky sú zadefinované nižšie. V zásade však nie je potrebné posielať kompletnú sadu údajov, hlavne ak sa dané údaje nevyskytujú vo Vašom systéme. Teda údaje, ktoré nemáte k dispozícii netreba posielať vôbec, a to ani prázdne či nulové hodnoty.

    <?xml version="1.0" encoding="UTF-8"?>
    <objects>
      <object>
        <data>
          <col name="import_id">1</col>
          <col name="delete">0</col>
          <col name="id_zakazky"/>
          <col name="action">1</col>
          <col name="category">1</col>
          <col name="makler_id">makler_id</col>
          ...
        </data>
        <lang_data>
          <lang name="sk">
            <col name="name">"><![CDATA[ Nadpis inzerátu ]]></col>
            <col name="description"><![CDATA[ text inzerátu ]]></col>
            ...
          </lang>
        </lang_data>
        <media>
          <image file="Celá URL adresa fotografie"></image>
          <image file="Celá URL adresa fotografie"></image>
          ...
        </media>
      </object>
      <object id="1">
        ...
      </object>
      ...
    </objects>

##### 2.3.2.1 Popis polí objects.xml

###### data

Ak sú niektoré parametre určené pre určité kategórie, vzťahujú sa zvačša k "predaju" a "prenájmu". Tieto paramtre nebudú mať efekt pre iné kategórie ako sú určené. Ich zadaním však nedôjde k žiadnej chybe. Ak je parameter povinný, tak je povinný iba pre dané kategórie.

Názov | Typ | Veľk. | Povinný | Číselník | Popis | Určené pre kategóriu
--- | --- | --- | --- | --- | --- | ---
import_id | varchar | 50 | áno |  | Vaše id inzerátu (systémové) - bude využité pri párovaní v našom systéme. | všetky
delete | varchar | 50 | nie |  | Príznak, či sa má inzerát zmazať. Ak je 1, nie je treba uviesť žiadne ďalšie polia okrem import_id. Sekcie lang_data a media sa môžu taktiež vynechať. | všetky
id_zakazky | varchar | 30 | nie |  | Interné číslo inzerátu v rámci RK | všetky
action | int | 2 | áno | action | Typ transkacie (pedaj, kúpa) viď. číselník. | všetky
category | int | 2 | áno | category | Kategória | všetky
state | char | 3 | áno | state | Štát | všetky
county | char | 5 | áno | county | Kraj | všetky
district | char | 7 | áno | district | Okres | všetky
region | char | 11 | áno | region | Obec | všetky
street | varchar | 50 | nie |  | Ulica + popisné číslo | všetky
makler_id | varchar | 30 | nie |  | Vaše id makléra, bude napárované podľa importu maklérov | všetky
price | float | 10,2 | áno |  | Cena | všetky
price_unit | int | 2 | áno | price_unit | Typ ceny (celkom ,m2, za mesiac...) | všetky
price_currency | int | 2 | áno | price_currency | Mena | všetky
ownership | int | 2 | áno | ownership | Druh vlastníctva | 3,4
flat_kind | int | 2 | áno | flat_kind | Dispozícia bytu | 4
house_kind | int | 2 | nie | house_kind | Kategória domu | 6
usable_area | int | 11 | áno |  | Úžitková plocha v m2 | 1,4,5,6,7,8,9,10
total_area | int | 11 | nie |  | Celková plocha v m2 | 2,3
plot_area | int | 11 | nie |  | Plocha parcely v m2 | 1,2,3,5,6,7,8,10
floor_area | int | 11 | nie |  | Celk. podlahová plocha v m2 | 4
building_area | int | 11 | nie |  | Zastavaná plocha v m2 | 1,2,5,6,7,8,10,11
living_area | int | 11 | nie |  | Obytná plocha v m2 | 10
offices_area | int | 11 | nie |  | Plocha kancelárií v m2 | 9
balcony_area | int | 11 | nie |  | Plocha balkónov v m2 | 4
loggie_area | int | 11 | nie |  | Plocha lodžií v m2 | 4
terrace_area | int | 11 | nie |  | Plocha terás v m2 | 4
cellar_area | int | 11 | nie |  | Plocha pivnice v m2 | 4,6
building_type | int | 2 | nie | building_type | Druh objektu (typ konštrukcie) | 1,2,4,5,6,7,8,9,10,11
condition | int | 2 | nie | condition | Stav objektu | 1,2,4,5,6,7,8,9,11
commercial_kind | int | 2 | nie | commercial_kind | Účel budovy | 2
parking_type | int | 2 | nie | parking_type | Druh parkovania | 2,4,5,6,7,8,9,10
estate_kind | int | 2 | nie | estate_kind | Druh pozemku | 3
object_kind | int | 2 | nie | object_kind | Poloha objektu | 6,11
object_type | int | 2 | nie | object_type | Typ domu | 6
hotel_kind | int | 2 | nie | hotel_kind | Typ zariadenia | 7
office_kind | int | 2 | nie | office_kind | Druh priestorov | 9
so_type | int | 2 | nie | so_type | Druh malých objektov | 11
object_location | int | 2 | nie | object_location | Umiestnenie objektu | 10
recreation_type | int | 2 | nie | recreation_type | Typ rekreácie | 10
equiped | int | 2 | nie | equiped | Zariadenie bytu | 4
road_type | int | 2 | nie | road_type | Prístupová cesta | 3,10
heating | int | 2 | nie | heating | Spôsob kúrenia | 4,6,10
water_heating | int | 2 | nie | wheating | Príprava teplej vody | 6,10
location | int | 2 | nie | location | Umiestnenie pozemku | 3
development | int | 2 | nie | development | Funkčné využitie pozemku | 3
terrene | int | 2 | nie | terrene | Terén | 3
windows | int | 2 | nie | windows | Okná | 4,6,10
electric | int | 2 | nie | electric | El. napätie | 4,6,10
toilets_type | int | 2 | nie | toilets_type | Typ WC | 10
water_source | int | 2 | nie | water_source | Typ WC | 10
toswimming | int | 2 | nie | distance | Vzdialenosť ku kúpalisku/jazeru | 10
toskiing | int | 2 | nie | distance | Vzdialenosť k vleku/lanovke | 10
togolf | int | 2 | nie | distance | Vzdialenosť ku golfovému ihrisku | 10
tocenter | int | 2 | nie | distance | Vzdialenosť do centra obce | 10
rooms | int | 3 | nie |  | Počet izieb (pre komerčné počet miestností, hál) | 1,2,6,7,9,10
floors | int | 3 | nie |  | Počet podlaží objektu | 1,2,4,5,6,7,8,9
floor_number | int | 3 | nie |  | Číslo podlažia v budove | 4
underground_floors | int | 1 | nie |  | Počet podzemnýcvh podlaží | 4
parking | int | 5 | nie |  | Počet parkovacích miest | 2,4,5,6,7,8,9
garage | int | 3 | nie |  | Počet garaží | 2,4,5,6,7,8,9
bathrooms | int | 3 | nie |  | Počet kúpeľní | 4,6,7,10
toilets | int | 3 | nie |  | Počet WC | 2,4,6,7,9,10
loggie | int | 3 | nie |  | Počet lodžií | 4,6
terrace | int | 3 | nie |  | Počet terás | 4,6
networks_1 | 0/1 | 1 | nie |  | Vodovod | 1,2,3,5,6,7,8,9,10
networks_2 | 0/1 | 1 | nie |  | Kanalizácia | 1,2,3,5,6,7,8,9,10
networks_3 | 0/1 | 1 | nie |  | Plyn | 1,2,3,5,6,7,8,9,10
networks_4 | 0/1 | 1 | nie |  | Elektrina | 1,2,3,5,6,7,8,9,10
flat_facilities_1 | 0/1 | 1 | nie |  | Výťah | 4
balcony | int | 3 | nie |  | Počet balkónov | 4,6
acceptance_year | int | 4 | nie |  | Rok výstavby | 6,10
reconstruction_year | int | 4 | nie |  | Rok rekonštrukcie | 6,10
gps_x | varchar | 20 | nie |  | GPS X | všetky
gps_y | varchar | 20 | nie |  | GPS Y | všetky
wgarden | 0/1 | 1 | nie |  | Zimná záhrada | 4,6,10
closet | 0/1 | 1 | nie |  | Šatník | 4,6
larder | 0/1 | 1 | nie |  | Zimná záhrada | 4
mezonet | 0/1 | 1 | nie |  | Mezonet | 4
core | 0/1 | 1 | nie |  | Murované jadro | 4
safedoors | 0/1 | 1 | nie |  | Bezpečnostné dvere | 4,6
alarm | 0/1 | 1 | nie |  | Alarm | 1,2,4,5,6,7,8,9
videogate | 0/1 | 1 | nie |  | Video vrátnik | 1,2,4,5,7,8,9
aircondition | 0/1 | 1 | nie |  | Klimatizácia | 1,2,4,5,6,7,8,9
cabletv | 0/1 | 1 | nie |  | Káblová TV | 4,6
internet | 0/1 | 1 | nie |  | Internet | 1,2,4,5,6,7,8,9
phoneline | 0/1 | 1 | nie |  | Telefónna linka | 1,2,4,5,6,7,8,9,10
garden | 0/1 | 1 | nie |  | Záhrada | 6,10
fence | 0/1 | 1 | nie |  | Oplotenie | 3,6,10
alcove | 0/1 | 1 | nie |  | Altánok | 6
fireplace | 0/1 | 1 | nie |  | Vnútorný krb | 6,10
fireplace_ext | 0/1 | 1 | nie |  | Vonkajší krb | 6,10
swimming | 0/1 | 1 | nie |  | Bazén | 6
sauna | 0/1 | 1 | nie |  | Sauna | 6
muscle | 0/1 | 1 | nie |  | Posilňovňa | 6
kitchen | 0/1 | 1 | nie |  | Kuchynka | 2,9
dock | 0/1 | 1 | nie |  | Nakladacia rampa | 1,2,9
security | 0/1 | 1 | nie |  | Strážna služba | 1,2,9
workshop | 0/1 | 1 | nie |  | Strážna služba | 1,2,9
smartvisite_id | int | 3 | nie |  | Smart Visite ID | všetky
detail_url | varchar | 255 | nie |  | URL nehnuteľnosti na Vašom webe | všetky

###### lang_data (jazykovo závislé údaje)

Momentálne podporujeme len jazyk SK, preto stačí generovať len položky do elementu <lang name="sk">

Názov | Typ | Veľk. | Povinný | Číselník | Popis | Určené pre kategóriu
--- | --- | --- | --- | --- | --- | ---
name | varchar | 100 | áno |  | Názov inzerátu | všetky
description | text |  | áno |  | Text inzerátu | všetky
elektrina_note | text |  | nie |  | Poznámka k elektrine | 3,10
plyn_note | text |  | nie |  | Poznámka k plynu | 3,10
kanalizacia_note | text |  | nie |  | Poznámka ku kanalizácii | 3,10
voda_note | text |  | nie |  | Poznámka k vode | 3,10

###### media (obrázky)

Momentálne časť media slúži iba na import fotografií, v budúcnosti možno pribudnú možnosti importu ďalšich formátov ako pdf, atd...

Pri exporte fotografií sú dôležité nasledujúce pravidlá:

- musia byť vo formáte JPG,
- optimálné rozlíšenie je do 1024x768px, väčši rozmer nie je problém, ale fotografie budú aj tak automaticky upravené na tieto veľkosti, čo zas zbytočne zaťaží proces importu,
- impotuje sa len jedna veľkosť fotografie, všetky pre nás potrebné náhľady si generujeme z tohto zdroja,
- vždy uvádzajte v exporte úplné URL adresy obrázkov,
- prvý obrázok zo zonamu je vždy "hlavný", ostatné sa preberajú v dodanom poradí, preto ak chcete zachovať určité poradie fotografií, musíte ich v danom poradí aj dodať.
- textové informácie k obrázkom (názov, popis) sú nepovinné, element <lang> nemusí byť exporte obsiahnutý vôbec, teda ani prázdny,

##### 2.3.2.2 Odpovedné XML po spracovaní

    <?xml version="1.0" encoding="UTF-8"?>
    <response>
      <object>
        <object_id>1</object_id>
        <status>Inzerát vytvorený</status>
        <status_code>1</status_code>
      </object>
      <object>
        ...
      </object>
    </response>

Kód stavu (status_code) | Stav (status) | Poznámka
--- | --- | ---
1 | Inzerát vytvorený | Pridaný nový inzerát
2 | Inzerát upravený | Upravený inzerát. object_id sa našlo v našej databáze, tak boli údaje inzerátu upravené.
3 | Inzerát vymazaný | tag deleted nastavený na 1, inzerát sa našiel v našej databáze a vymazal sa
4 | Inzerát neexistuje | Snaha o zmazanie inzerátu, ktorý neexistuje v našej databáze
5 | Chybné alebo chýbajúce povinné údaje: nasleduje zoznam chybných polí | Nevyplnili ste niektoré z povinných polí.