DomuHQ Partner Listing Sync API – Dokumentace

DomuHQ Partner Listing Sync API

Toto je technická dokumentace pro CRM dodavatele integrující synchronizaci inzerátů s DomuHQ. Naše API je postaveno na specifikaci Sreality.cz addAdvert v4.0.0. Každý název pole a hodnota číselníku odpovídá oficiální importní specifikaci Sreality.

Pokud již implementujete Sreality XML-RPC, jedná se o stejný payload ve formátu JSON.

Kompletní dokumentaci s příklady kódu, curl příkazy a ukázkami JSON požadavků/odpovědí najdete v PDF verzi ke stažení. Pro dotazy nás kontaktujte na integrations@domuhq.cz.

Endpoint a prostředí

Odeslání inzerátu: POST /v1/domu-hq/listing/external/sync/listing

Každé volání vytvoří nebo aktualizuje právě jeden inzerát. Pro synchronizaci více inzerátů opakujte volání na straně CRM.

• Sandbox / Dev: https://api.dev.domuhq.cz
• Produkce: https://api.domuhq.cz

Autentizace

Každý požadavek vyžaduje tyto hlavičky:

• X-API-Key (povinný): Statický klíč přidělený vám. Jeden na partnera.
• X-Source (povinný): Váš partnerský slug, např. llr, softreal, realitni-spravce.
• Idempotency-Key (povinný): UUID v4 na logickou operaci. Při opakování použijte stejný.
• Content-Type: application/json (UTF-8).

Zdrojové IP adresy jsou povoleny na bráně. Sdělte nám CIDR rozsah hostitele, ze kterého budete odesílat.

Pole na nejvyšší úrovni

• advert_rkid (string, povinný): ID vašeho inzerátu. Klíč pro upsert, musí být unikátní v rámci vašeho CRM.
• client_login (email, povinný): Email makléře. Musí existovat v DomuHQ.
• seller_rkid (string, volitelný): ID makléře pro křížovou korelaci.
• agency_rkid (string, volitelný): ID kanceláře pro křížovou korelaci.
• client_name (string, volitelný): Zobrazované jméno makléře.
• contact_gsm (string, volitelný): Telefonní číslo makléře.
• advert_data (objekt, povinný): Payload inzerátu se všemi poli nemovitosti.
• photos (pole 1-10, povinné): Objekty fotografií s URL, pořadím a kategorizací místností.

Payload inzerátu (advert_data)

Názvy polí odpovídají struktuře Sreality addAdvert.advert_data. Číselníková pole používají celočíselné kódy dle specifikace Sreality. API přijímá tyto skupiny polí:

• Kategorie (povinné): advert_function (2=pronájem), advert_type (1=byt, 2=dům), advert_subtype (číselník dispozice)
• Cena (povinné): advert_price, advert_price_currency (1=CZK, 2=USD, 3=EUR), advert_price_unit (2=měsíčně), provize, vratná kauce
• Popis (povinný): description (max 10 000 znaků)
• Lokalita: locality_city (povinný), locality_inaccuracy_level (povinný), GPS souřadnice, RUIAN kód, ulice, městská část, PSČ
• Vlastnosti budovy: building_type (1-8), building_condition (1-10), usable_area, floor_number, floors, výška stropu, rok výstavby, rok rekonstrukce, typ vlastnictví
• Vybavení: balkón, lodžie, sklep, terasa, garáž, výtah, bezbariérový přístup, solární panely
• Vlastnosti: furnished (1=ano, 2=ne, 3=částečně), vytápění, elektřina, plyn, voda, kanalizace, internet, parkování
• Energie: energy_efficiency_rating (1=A až 7=G), průkaz energetické náročnosti, kWh/m2/rok
• Dostupnost: typ nájmu (nájem/podnájem), ready_date (ISO datum), stavové příznaky

Jakékoliv další pole ze specifikace Sreality, které není uvedeno výše, je uchováno v raw_partner_payload a vráceno jako informační varování.

Klíčové hodnoty číselníků

• Dispozice (advert_subtype): 2=1+kk, 3=1+1, 4=2+kk, 5=2+1, 6=3+kk, 7=3+1, 8=4+kk, 9=4+1, 10=5+kk, 11=5+1, 12=6+, 16=atypický, 47=pokoj
• Typ budovy: 1=dřevěná, 2=cihlová, 3=kamenná, 4=montovaná, 5=panelová, 6=skeletová, 7=smíšená, 8=modulární
• Stav: 1=velmi dobrý, 2=dobrý, 3=špatný, 4=ve výstavbě, 5=projekt, 6=novostavba, 7=k demolici, 8=před rekonstrukcí, 9=po rekonstrukci, 10=v rekonstrukci

Fotografie

1-10 fotografií na inzerát. Každá fotografie je objekt s: data (URL, povinné), main (1=hlavní), order, alt (popisek), photo_kind (photo/photo_360/floor_plan) a room_type (32 kategorií od obývacího pokoje po výhled na hory). Obrázky stahujeme a nahráváme na náš CDN. JPG, PNG, WebP, GIF, max 10 MB.

Odpovědi

• 200 Úspěch: Vrací advert_rkid (echo), advert_id (DomuHQ UUID), status (active), action (created/updated), pole varování.
• 422: Chyba validace. Inzerát neuložen. Opravte pole, opakujte s novým Idempotency-Key.
• 409: Konflikt. Inzerát byl smazán, nelze obnovit přes partnerské API.
• 401/403/400/429/500: Chyby autentizace, IP není povolena, chybný JSON, překročen limit, chyba serveru. Při 5xx bezpečné opakovat se stejným Idempotency-Key.

Kontakt

Pro dotazy k integraci, testovací přístupy a partnerské dotazy: integrations@domuhq.cz

Referenční číselníky: Sreality import specifikace v4.0.0 (admin.sreality.cz/doc/import.pdf)