Základná URL: https://doomio.cz/api/v1. Kľúč posielajte iba zo svojho servera cez HTTPS v hlavičke Authorization: Bearer <key>. Kľúče fungujú nezávisle od relácií prehliadača. Zvoľte prístup len na čítanie alebo čítanie/zápis; kľúče zrušíte vo svojom účte. Kľúč môže pristupovať iba k vašim osobným ponukám alebo k ponukám vašej aktuálnej kancelárie. Po opustení kancelárie, deaktivácii účtu, uplynutí platnosti alebo zrušení sa kľúč deaktivuje.

1. Vytvorte koncept

Každá nová ponuka potrebuje stabilné externalId z vášho CRM, jedinečné v rámci vášho osobného účtu alebo kancelárie. Duplikát vráti 409; načítajte existujúcu ponuku a PATCH ju. ID zostávajú rezervované aj vtedy, keď je ponuka stiahnutá.

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
  }'

Odpoveď je 201 Created, {"data": {...}}, s ID ponuky, hlavičkou Location a ETag. Text sa poskytuje v sourceLocale; existujúci proces prekladu pripraví ostatné jazykové verzie 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ávajte JPEG, PNG alebo WebP, maximálne 8 MiB a 40 megapixelov na obrázok, najviac 30 obrázkov. Fotografie prechádzajú rovnakou kontrolou ako nahrania z webu. Publikovanie vyžaduje názov, adresu, krajinu, typ nehnuteľnosti, aspoň jednu schválenú fotografiu a oprávnenie na publikovanie. Ponuky kancelárie sa riadia existujúcimi pravidlami viditeľnosti kancelárie; osobné ponuky potrebujú aktívne publikovanie zakúpené v účte Doomio. Propagačné ponuky si zachovávajú svoje existujúce limity a potvrdenie práv. API kľúče nekupujú plány ani sociálnu propagáciu.

Skontrolujte publiclyVisible, status a photoReviewError v odpovedi. Exspirovaná ponuka alebo neúspešná kontrola fotografie nie je verejne viditeľná. DELETE stiahne ponuku do konceptu; zachová jej ID aj históriu. Odstránenie poslednej fotografie tiež stiahne ponuku.

Endpointy

Polia a odpovede

Zapisovateľné polia: title, description, sourceLocale, type, transactionType, price, currency, country, address, city, postalCode, latitude, longitude, rooms, bedrooms, bathrooms, usableArea, landArea, contactEmail, contactPhone. externalId sa priraďuje pri vytvorení. Neznáme polia vracajú 422. Presné hranice a podporované krajiny/jazyky nájdete v OpenAPI. Ceny sú desatinné reťazce, plochy sú v metroch štvorcových, súradnice sú číselné WGS84. Hodnoty meny: CZK, EUR, USD, GBP, PLN. Typy: apartment, house, land, commercial, other, development. Transakcie: sale, rent.

Zoznamy vracajú {"data": [...], "pagination": {"limit": 50, "nextAfter": 123}}. Opakujte s ?after=123; nextAfter: null znamená koniec. Ponuku z CRM môžete načítať pomocou ?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"}'

Voliteľné If-Match pri PATCH, publikovaní, stiahnutí a operáciách s obrázkami zabraňuje prepísaniu ponuky, ktorá sa zmenila od vášho posledného GET. Nesúlad vráti 412; načítajte ponuku a vyriešte konflikt. Maximálna veľkosť JSON požiadavky: 128 KiB. Limit: 120 overených požiadaviek za minútu na účet/kanceláriu naprieč všetkými jej kľúčmi; nadbytočné požiadavky vracajú 429 a Retry-After: 60. Skontrolujte X-RateLimit-Remaining. Nie je potrebný žiadny prístup z prehliadača cez cross-origin: integrácie patria na váš server.

Chyby používajú {"error":{"code":"validation_failed","message":"..."}}. Stavy: 400 neplatná požiadavka, 401 chýbajúci/neplatný/exspirovaný kľúč, 403 iba na čítanie kľúč alebo chýbajúce oprávnenie na publikovanie, 404 ponuka/obrázok mimo vášho rozsahu alebo neexistuje, 405 metóda, 409 duplicitné externalId, 412 zastarané ETag, 413 príliš veľké nahranie/telo, 415 Content-Type, 422 neplatné polia/validácia fotografie/publikovania, 429 obmedzenie rýchlosti, 500 dočasná chyba servera. Každá odpoveď obsahuje X-Request-ID; pri hlásení chyby ho uveďte, nikdy nie váš tajný kľúč.

Inštalácia klienta

Vyžaduje Python 3.10 alebo novší, bez balíkov tretích strán. Stiahnite si klienta a súbor kľúča .env, oboje uchovávajte mimo verejného webového adresára, potom spustite:

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 objektov ponúk v tvare pre vytvorenie. sync vyhľadáva externé ID, vytvára chýbajúce koncepty a aktualizuje existujúce ponuky. Nemaže ponuky neprítomné v súbore, automaticky nenahráva fotografie ani ich nepublikuje. Upload/publish/withdraw sú explicitné príkazy. Toto je všeobecný klient na integráciu JSON; existujúce CRM produkty stále potrebujú vlastné mapovanie polí alebo konektor.