Vývojářská dokumentace · JSON REST API v1

Pro realitní kanceláře i soukromé klienty: vytvořte si klíč ve svém účtu a propojte své CRM nebo web. API přijímá a vrací JSON. Nové inzeráty se vytvářejí jako koncepty; fotografie a publikování mají samostatné endpointy.

Vytvořit API klíč OpenAPI 3.1 JSON Stáhnout klienta v Pythonu

Základní URL: https://doomio.cz/api/v1. Odesílejte svůj klíč pouze ze serveru přes HTTPS, v hlavičce Authorization: Bearer <key>. Klíče fungují nezávisle na relacích v prohlížeči. Zvolte přístup pouze pro čtení nebo pro čtení/zápis; klíče můžete zrušit ve svém účtu. Klíč může přistupovat pouze k vašim osobním inzerátům nebo k inzerátům vaší aktuální kanceláře. Při odchodu z kanceláře, deaktivaci účtu, vypršení platnosti nebo zrušení se klíč deaktivuje.

1. Vytvořte koncept

Každý nový inzerát potřebuje stabilní externalId z vašeho CRM, jedinečné v rámci vašeho osobního účtu nebo kanceláře. Duplikát vrátí 409; načtěte existující inzerát a upravte jej metodou PATCH. ID zůstávají rezervovaná, když je inzerát stažen.

curl https://doomio.cz/api/v1/properties \
  -H "Authorization: Bearer $DOOMIO_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
    "externalId": "CRM-12345",
    "title": "Apartment in Valencia",
    "description": "A bright two-bedroom apartment near the park.",
    "sourceLocale": "en",
    "country": "es", "city": "Valencia",
    "address": "Valencia, Spain",
    "type": "apartment", "transactionType": "sale",
    "price": "245000.00", "currency": "EUR",
    "bedrooms": 2, "usableArea": 78.5
  }'

Odpověď je 201 Created, {"data": {...}}, s ID inzerátu, hlavičkou Location a ETag. Text se zadává v sourceLocale; stávající pracovní postup překladu připraví ostatní jazykové verze webu.

2. Nahrajte fotografie a publikujte

curl https://doomio.cz/api/v1/properties/123/images \
  -H "Authorization: Bearer $DOOMIO_API_KEY" -F '[email protected]'

curl -X POST https://doomio.cz/api/v1/properties/123/publish \
  -H "Authorization: Bearer $DOOMIO_API_KEY"

Nahrávejte JPEG, PNG nebo WebP, maximálně 8 MiB a 40 megapixelů na obrázek, nejvýše 30 obrázků. Fotografie procházejí stejnou kontrolou jako při nahrání přes web. Publikování vyžaduje název, adresu, zemi, typ nemovitosti, alespoň jednu schválenou fotografii a oprávnění k publikaci. Inzeráty kanceláře se řídí stávajícími pravidly viditelnosti kanceláře; osobní inzeráty vyžadují aktivní publikaci zakoupenou v účtu Doomio. Propagační nabídky si zachovávají stávající limity a potvrzení práv. Prostřednictvím API klíčů nelze nakupovat tarify ani propagaci na sociálních sítích.

Zkontrolujte publiclyVisible, status a photoReviewError v odpovědi. Vypršený inzerát nebo neúspěšná kontrola fotografie nejsou veřejně viditelné. DELETE stáhne inzerát do konceptu; zachová jeho ID i historii. Odstranění poslední fotografie také stáhne inzerát.

Endpointy

Metoda a cesta	Chování
`GET /properties`	Vaše inzeráty, včetně konceptů. Volitelné `limit` (1–100, výchozí 50), `after` (kurzor ID), `externalId`, `status` (koncept/publikováno).
`POST /properties`	Vytvoří koncept. Povinné: `externalId`, title, `sourceLocale`, country, type, `transactionType`, price, currency.
`GET /properties/{id}`	Jeden inzerát a jeho `ETag`.
`PATCH /properties/{id}`	Aktualizuje zadaná pole; vynechaná pole zůstávají beze změny. `externalId` je neměnné. Vlastnictví, fakturace, sociální propagaci a platnost nelze prostřednictvím tohoto endpointu změnit.
`DELETE /properties/{id}`	Stáhne inzerát; opakované volání jsou bezpečné.
`POST /properties/{id}/publish`	Ověří a publikuje; platí stávající pravidla publikování.
`POST /properties/{id}/images`	Multipart nahrání, pole `file`. Vrací inzerát s ID obrázku.
`DELETE /properties/{id}/images/{imageId}`	Odstraní jeden z obrázků tohoto inzerátu.

Pole a odpovědi

Zapisovatelná pole: title, description, sourceLocale, type, transactionType, price, currency, country, address, city, postalCode, latitude, longitude, rooms, bedrooms, bathrooms, usableArea, landArea, contactEmail, contactPhone. externalId je přiřazeno při vytvoření. Neznámá pole vracejí 422. Přesné meze a podporované země/jazyky viz OpenAPI. Ceny jsou desetinné řetězce, plochy jsou v metrech čtverečních, souřadnice jsou číselné WGS84. Měnové hodnoty: CZK, EUR, USD, GBP, PLN. Typy: apartment, house, land, commercial, other, development. Transakce: sale, rent.

Seznamy vracejí {"data": [...], "pagination": {"limit": 50, "nextAfter": 123}}. Opakujte s ?after=123; nextAfter: null znamená konec. Inzerát z CRM můžete načíst pomocí ?externalId=CRM-12345.

curl -X PATCH https://doomio.cz/api/v1/properties/123 \
  -H "Authorization: Bearer $DOOMIO_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'If-Match: "ETAG-FROM-LAST-GET"' \
  --data '{"price":"239000.00"}'

Volitelná hlavička If-Match při úpravě metodou PATCH, zveřejnění, stažení a práci s fotografiemi zabrání přepsání inzerátu změněného od vašeho posledního GET. Nesoulad vrátí 412; načtěte inzerát a vyřešte konflikt. Maximální JSON požadavek: 128 KiB. Limit: 120 ověřených požadavků za minutu na účet/kancelář napříč všemi jejími klíči; nadlimitní požadavky vrátí 429 a Retry-After: 60. Sledujte X-RateLimit-Remaining. Není vyžadován žádný přístup z prohlížeče přes cross-origin: integrace musí běžet na vašem serveru.

Chyby používají {"error":{"code":"validation_failed","message":"..."}}. Stavy: 400 chybně vytvořený požadavek, 401 chybějící/neplatný/vypršený klíč, 403 klíč jen pro čtení nebo chybějící oprávnění k publikaci, 404 inzerát/obrázek mimo váš rozsah nebo chybí, 405 metoda, 409 duplicitní externalId, 412 zastaralý ETag, 413 příliš velké nahrání/tělo, 415 Content-Type, 422 neplatná pole/ověření fotografie/publikování, 429 omezení rychlosti, 500 dočasná chyba serveru. Každá odpověď obsahuje X-Request-ID; uveďte jej při hlášení chyby, nikdy svůj tajný klíč.

Nainstalujte klienta

Vyžaduje Python 3.10 nebo novější, bez balíčků třetích stran. Stáhněte si klienta a soubor s klíčem .env, uložte oba mimo veřejný webový adresář a poté spusťte:

chmod 600 doomio-api-key.env
python3 doomio_client.py --env doomio-api-key.env list
python3 doomio_client.py --env doomio-api-key.env sync listings.json
python3 doomio_client.py --env doomio-api-key.env upload 123 living-room.jpg
python3 doomio_client.py --env doomio-api-key.env publish 123
python3 doomio_client.py --env doomio-api-key.env withdraw 123

listings.json je pole objektů inzerátů ve formátu pro vytvoření. sync vyhledává externí ID, vytváří chybějící koncepty a aktualizuje stávající inzeráty. Nesmaže inzeráty, které v souboru chybí, automaticky nenahraje fotografie ani je nepublikuje. Nahrání/publikování/stažení jsou explicitní příkazy. Jde o obecný klient pro JSON integraci; existující CRM produkty stále potřebují vlastní mapování polí nebo konektor.