Domoplius importas V2

Greita pradžia

Paruoškite UTF-8 XML arba JSON dokumentą ir paskelbkite jį viešu HTTP(S) URL. Kiekvienas sėkmingas atsakymas yra visa tuo URL pateikiama dabartinė kopija.

1. 1Pasirinkite XML arba JSON šabloną, pakeiskite pavyzdines reikšmes ir laukų žinyne patikrinkite savo kategoriją.
2. 2Kiekvienam skelbimui skirkite nekintantį external_id ir toje pačioje kategorijoje jo nekartokite.
3. 3Paskelbkite srautą viešu URL ir perduokite jį bei skelbimų savininko paskyrą Domoplius kontaktui.

XML ir JSON yra struktūriniai šablonai. Patikrinkite skaitinius vietų ir parinkčių ID bei nuotraukų URL.

<?xml version="1.0" encoding="UTF-8"?>
<domoplius xmlns="https://domoplius.lt/xml/import/v2" version="2">
  <!--Replace location and option IDs using the versioned endpoints, and supply public image URLs.-->
  <listings>
    <flat>
      <external_id>100001</external_id>
      <action_type>1</action_type>
      <price_eur>145000</price_eur>
      <administrative_unit_id>461</administrative_unit_id>
      <settlement_id>1</settlement_id>
      <flat_size>50.5</flat_size>
      <flat_rooms>1</flat_rooms>
    </flat>
  </listings>
</domoplius>

Importo eiga

Kiekvienas šaltinio vykdymas pereina tuos pačius etapus. Atskiro įrašo klaida nesustabdo tinkamų įrašų, tačiau viso srauto patikimumas lemia, ar galima šalinti trūkstamus skelbimus.

1. 1. Atsisiuntimas

   Importuotojas saugiai atsisiunčia viešą HTTP(S) srautą, laikydamasis dydžio, laiko ir nukreipimų ribų.

2. 2. Pirminė patikra

   Tikrinama V2 vardų sritis, versija, plokšti skelbimo laukai, kolekcijų struktūra, unikalios tapatybės ir ar nėra DTD bei išorinių esybių.

3. 3. Srautinis apdorojimas

   Įrašai skaitomi po vieną, normalizuojami, validuojami ir susiejami su kategorijų bei adresų reikšmėmis.

4. 4. Įrašymas

   Galiojantys įrašai sukuriami arba atnaujinami; klaidingi įrašai praleidžiami ir įtraukiami į ataskaitą.

5. 5. Suderinimas

   Trūkstami skelbimai vertinami tik sėkmingai apdorojus visus įjungtus to savininko šaltinius ir praėjus pašalinimo apsaugas.

6. 6. Ataskaita

   Administratorius peržiūri rezultatą, įspėjimus ir atmestų įrašų priežastis prieš įjungdamas ar palikdamas aktyvų šaltinį.

Srauto reikalavimai

Kad XML arba JSON srautą būtų galima importuoti, laikykitės šių pagrindinių taisyklių.

Kainos ir trumpalaikė nuoma

Kainas pateikite eurais, su ne daugiau kaip dviem skaitmenimis po taško, pavyzdžiui, 10.01. Veiksmams 1 ir 3 būtina price_eur. Veiksmas 9 leidžiamas tik Lietuvos butams ir namams: būtina short_rent_day_eur, o price_eur neprivaloma ir nepateikta išvaloma.

Sklypo plotas

Naudokite site_size_a arais (1 aras = 100 m²). Nepateikus neprivalomo sklypo ploto, ankstesnė reikšmė išvaloma.

Tuščios reikšmės ir tipai

Tušti ar tik tarpų turintys XML laukai ir JSON null išvalo neprivalomas reikšmes. Tuščios JSON eilutės išvalo tekstą, tačiau netinka skaičiams ar loginėms reikšmėms. Trūkstama privaloma arba sąlygiškai privaloma reikšmė atmeta tik skelbimą. Nepateikti arba tušti contact_name, contact_phone ir contact_email imami iš susieto brokerio, tada iš šaltinio savininko; jie neišvalomi. Neradus brokerio, savininko priskyrimui turi būti įjungtas šaltinio atsarginio priskyrimo nustatymas. contact_secondary_phone atsarginės reikšmės neturi ir nepateiktas išvalomas.

Semantinė patikra

Prieš perduodami srautą, patikrinkite jį validatoriumi. Tikrinami privalomi laukai, leidžiamos reikšmės, adresų ryšiai ir koordinačių pora. Neteisinga lauko reikšmė atmeta skelbimą, o struktūros klaida – visą srautą. Tikslias ribas rasite laukų apraše.

Komercinių patalpų paskirtys

Kategorijoms commercial ir foreign_commercial naudokite commercial_room_purposes su ID iš laukų aprašo. XML formatu kartokite commercial_room_purpose_id elementus, JSON formatu pateikite masyvą, pavyzdžiui, "commercial_room_purposes": [408, 410]. Kolekciją naudokite ir vienai paskirčiai. Nepateikus kolekcijos arba pateikus tuščią sąrašą, ankstesnės paskirtys išvalomos.

XML struktūra ir koduotė

Naudokite UTF-8 XML su <domoplius xmlns="https://domoplius.lt/xml/import/v2" version="2"><listings>…</listings></domoplius>. Skelbimo vienetiniai laukai pateikiami tiesiogiai kategorijos elemente; įdedamos kartotinės features, photos ir commercial_room_purposes kolekcijos.

JSON struktūra ir koduotė

Naudokite UTF-8 JSON su aukščiausio lygio listings masyvu ir be version lauko. Kiekviename elemente tiesiogiai pateikiama category ir jo laukai; features, photos ir commercial_room_purposes yra masyvai.

CDATA ir saugumas

Tekstui galima naudoti CDATA. DTD, DOCTYPE ir išorinės esybės draudžiamos; tokį failą importuotojas atmeta.

Tekstas

Aprašymuose HTML žymos pašalinamos, o <br> paverčiama nauja eilute. Siųskite tekstą, o ne paruoštą puslapio maketą.

Skaičiai ir datos

Kainoms ir kitiems skaičiams rekomenduojamas taškas kaip dešimtainis skirtukas. Statybos ir rekonstrukcijos datos priimamos YYYY arba YYYY-MM forma.

Viešas URL

Palaikomi HTTP ir HTTPS adresai; rekomenduojame HTTPS su galiojančiu sertifikatu. Tiesioginė GET užklausa turi grąžinti XML arba JSON srautą be prisijungimo, slapukų ar JavaScript patikros. Saugūs nukreipimai palaikomi, tačiau geriau pateikti tiesioginį URL.

Kaip atnaujinami skelbimai

Domoplius atpažįsta skelbimą pagal Domoplius paskyrą (skelbimų savininką), kategoriją ir external_id. Šios tapatybės nekeiskite, kai keičiasi kiti skelbimo duomenys.

Naujas skelbimas

Naujas external_id sukuria naują skelbimą. ID turi būti teigiamas, nekintantis ir unikalus savo kategorijoje tai pačiai Domoplius paskyrai.

Atnaujinimas

Ta pati kategorija ir external_id atnaujina esamą tos paskyros skelbimą, net jei įrašas perkeliamas tarp jos registruotų XML URL. Kitoje kategorijoje tas pats external_id gali žymėti kitą skelbimą.

Kategorijos keitimas

Perkėlus įrašą į kitą kategoriją sukuriama nauja tapatybė. Ankstesnės kategorijos įrašas tampa trūkstamas ir gali būti pašalintas.

Visas sąrašas

Sėkmingai atsisiuntus XML, tame URL nepateikti įrašai, įskaitant visus praleistos kategorijos įrašus, nebelaikomi pateikiamais to šaltinio. Skelbimą saugo narystė bet kuriame neatsisakytame šaltinyje, įskaitant išjungtus ar archyvuotus šaltinius. Šią apsaugą panaikina aiškus šaltinio atsisakymas.

Validacija ir klaidos

Klaidos vertinamos dviem lygiais: vieno skelbimo klaida gali būti izoliuota, o srauto patikimumo klaida sustabdo visą vykdymą ir trūkstamų skelbimų suderinimą.

Lietuvos ir užsienio vietos

Užsienio skelbimai naudoja country_id ir city_id iš šalių bei miestų API; miestas turi priklausyti šaliai. Lietuvos skelbimuose naudokite esamus aktyvius Domoplius skaitinius administrative_unit_id, settlement_id, microdistrict_id ir street_id. Jie tiesiogiai atitinka placereg_* įrašus ir turi sudaryti vieną hierarchiją.

1. 1. Administracinis vienetas

   Naudokite grąžintą skaitinį id.

   /api/v2/imports/locations/administrative-unitsKopijuoti

   GET /api/v2/imports/locations/administrative-units

2. 2. Gyvenvietė

   Filtruokite pagal administrative_unit_id.

   /api/v2/imports/locations/settlements?administrative_unit_id=461Kopijuoti

   GET /api/v2/imports/locations/settlements?administrative_unit_id=461

3. 3. Mikrorajonas

   Jei taikoma, filtruokite pagal settlement_id.

   /api/v2/imports/locations/microdistricts?settlement_id=1Kopijuoti

   GET /api/v2/imports/locations/microdistricts?settlement_id=1

4. 4. Gatvė

   Filtruokite pagal settlement_id ir, jei reikia, microdistrict_id.

   /api/v2/imports/locations/streets?settlement_id=1Kopijuoti

   GET /api/v2/imports/locations/streets?settlement_id=1

<administrative_unit_id>461</administrative_unit_id>
<settlement_id>1</settlement_id>
<microdistrict_id>31</microdistrict_id>
<street_id>22328</street_id>

Nuotraukos ir vaizdo įrašai

Nuotraukas ir vaizdo įrašą nurodykite pačiame skelbimo įraše.

Tvarka ir pagrindinė nuotrauka

Siųskite iki 30 URL norima tvarka. Pirmoji sėkmingai paruošta nuotrauka tampa pagrindine, o likusių tvarka išsaugoma.

Nuotraukų URL

Naudokite viešus HTTP(S) adresus, kuriuos Domoplius gali atsisiųsti be prisijungimo.

Nuotraukų išvalymas

Kiekviename vykdyme siųskite visą norimą rinkinį. Jei photos elemento nėra arba jis tuščias, anksčiau importuotos nuotraukos pašalinamos.

YouTube vaizdo įrašas

Naudokite video_url su absoliučiu http:// arba https:// YouTube URL: watch?v=, youtu.be/, embed/, shorts/, v/ arba vi/. Palaikomas ir youtube-nocookie.com. V2 nepriima vien vaizdo ID. Nepateikus ankstesnis vaizdo įrašas išvalomas.

XML, XSD, JSON ir JSON Schema

XML/XSD ir JSON/JSON Schema generuojami iš to paties V2 laukų registro.

XML ir JSON yra struktūriniai šablonai. Patikrinkite skaitinius vietų ir parinkčių ID bei nuotraukų URL.

<?xml version="1.0" encoding="UTF-8"?>
<domoplius xmlns="https://domoplius.lt/xml/import/v2" version="2">
  <!--Replace location and option IDs using the versioned endpoints, and supply public image URLs.-->
  <listings>
    <flat>
      <external_id>100001</external_id>
      <action_type>1</action_type>
      <contact_name>Partnerio brokeris</contact_name>
      <contact_phone>+37060000000</contact_phone>
      <contact_email>[email protected]</contact_email>
      <price_eur>145000</price_eur>
      <administrative_unit_id>461</administrative_unit_id>
      <settlement_id>1</settlement_id>
      <microdistrict_id>31</microdistrict_id>
      <street_id>22328</street_id>
      <building_number>12A</building_number>
      <unit_number>4</unit_number>
      <hide_unit_number>false</hide_unit_number>
      <latitude>54.687157</latitude>
      <longitude>25.279652</longitude>
      <description>Šviesus butas.</description>
      <flat_size>50.5</flat_size>
      <flat_rooms>1</flat_rooms>
      <window_directions>n,e</window_directions>
      <features>
        <feature_id>79</feature_id>
      </features>
      <photos>
        <photo_url>https://example.lt/photo.jpg</photo_url>
      </photos>
    </flat>
    <commercial>
      <external_id>100002</external_id>
      <action_type>1</action_type>
      <contact_name>Partnerio brokeris</contact_name>
      <contact_phone>+37060000000</contact_phone>
      <contact_email>[email protected]</contact_email>
      <price_eur>145000</price_eur>
      <administrative_unit_id>461</administrative_unit_id>
      <settlement_id>1</settlement_id>
      <microdistrict_id>31</microdistrict_id>
      <street_id>22328</street_id>
      <building_number>12A</building_number>
      <unit_number>4</unit_number>
      <latitude>54.687157</latitude>
      <longitude>25.279652</longitude>
      <description>Komercinės patalpos.</description>
      <is_price_for_all_place>false</is_price_for_all_place>
      <commercial_room_size>50.5</commercial_room_size>
      <commercial_room_purposes>
        <commercial_room_purpose_id>408</commercial_room_purpose_id>
        <commercial_room_purpose_id>410</commercial_room_purpose_id>
      </commercial_room_purposes>
      <features/>
      <photos>
        <photo_url>https://example.lt/photo.jpg</photo_url>
      </photos>
    </commercial>
  </listings>
</domoplius>

{
    "listings": [
        {
            "category": "flat",
            "external_id": 100001,
            "action_type": 1,
            "contact_name": "Partnerio brokeris",
            "contact_phone": "+37060000000",
            "contact_email": "[email protected]",
            "price_eur": 145000,
            "administrative_unit_id": 461,
            "settlement_id": 1,
            "microdistrict_id": 31,
            "street_id": 22328,
            "building_number": "12A",
            "unit_number": "4",
            "hide_unit_number": false,
            "latitude": 54.687157,
            "longitude": 25.279652,
            "description": "Šviesus butas.",
            "flat_size": 50.5,
            "flat_rooms": 1,
            "window_directions": "n,e",
            "features": [
                79
            ],
            "photos": [
                "https://example.lt/photo.jpg"
            ]
        },
        {
            "category": "commercial",
            "external_id": 100002,
            "action_type": 1,
            "contact_name": "Partnerio brokeris",
            "contact_phone": "+37060000000",
            "contact_email": "[email protected]",
            "price_eur": 145000,
            "administrative_unit_id": 461,
            "settlement_id": 1,
            "microdistrict_id": 31,
            "street_id": 22328,
            "building_number": "12A",
            "unit_number": "4",
            "latitude": 54.687157,
            "longitude": 25.279652,
            "description": "Komercinės patalpos.",
            "is_price_for_all_place": false,
            "commercial_room_size": 50.5,
            "commercial_room_purposes": [
                408,
                410
            ],
            "features": [],
            "photos": [
                "https://example.lt/photo.jpg"
            ]
        }
    ]
}

Dažnos klaidos

Keičiama tapatybė

Pakeitus external_id arba kategoriją sukuriama kita tapatybė, todėl ankstesnis skelbimas gali būti pažymėtas kaip trūkstamas.

Naudojami nedokumentuoti pavadinimai ar struktūra

Nežinomi laukai, daugiskaitos kategorijos ir senos contact, pricing, location, content ar attributes grupės atmetamos.

Naudojama netinkama vietos tapatybė

Lietuvos vietoms reikia esamų skaitinių Domoplius ID, o užsienio vietoms – paskelbtų skaitinių šalies ir miesto ID.

Praleidžiamos nuotraukos

Nuotraukoms taikoma bendra V2 pilnos kopijos taisyklė: nepateikus photos, ankstesnės importo nuotraukos pašalinamos.

video_url siunčiamas kaip loginė reikšmė

Siųskite palaikomą URL. Loginė reikšmė vaizdo įrašo neidentifikuoja.

Bandoma išvalyti privalomą lauką

Privalomi ir sąlyginai privalomi duomenys turi išlikti galiojantys kiekviename įraše; tuščias elementas tokį įrašą atmeta.

Versijos ir pakeitimai

V2 yra numatytoji naujų šaltinių versija. XML ir JSON turi vienodą laukų kontraktą ir pilnos momentinės kopijos semantiką.

Pakeitimų istorija

Import V2 · 2026-09-17

Dabartinis V2 kontraktas: XML ir JSON pilnos kopijos, dešimt kategorijų, skaitiniai vietų ID, kainos eurais, sklypo plotas arais, komercinių paskirčių kolekcijos ir absoliutūs HTTP(S) YouTube URL. Šį kontraktą aprašo generuojami pavyzdžiai, XSD ir JSON Schema.