Базова URL: https://doomio.cz/api/v1. Надсилайте свій ключ лише зі свого сервера через HTTPS, у заголовку Authorization: Bearer <key>. Ключі працюють незалежно від браузерних сесій. Оберіть доступ лише для читання або читання/запису; відкликайте ключі у своєму обліковому записі. Ключ може мати доступ лише до ваших особистих оголошень або до оголошень вашого поточного агентства. Після виходу з агентства, деактивації облікового запису, завершення строку дії або відкликання ключа доступ вимикається.

1. Створіть чернетку

Кожне нове оголошення потребує стабільного externalId із вашої CRM, унікального в межах вашого особистого облікового запису або агентства. У разі дубліката повертається 409; отримайте наявне оголошення та PATCH його. Ідентифікатори залишаються зарезервованими, коли оголошення знято.

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

Відповідь має формат 201 Created, {"data": {...}}, з ідентифікатором оголошення, заголовком Location і ETag. Текст подається мовою sourceLocale; наявний робочий процес перекладу готує інші мови вебсайту.

2. Завантажте фото та опублікуйте

curl https://doomio.cz/api/v1/properties/123/images \
  -H "Authorization: Bearer $DOOMIO_API_KEY" -F 'file=@living-room.jpg'

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

Завантажуйте JPEG, PNG або WebP, максимум 8 MiB і 40 мегапікселів на зображення, максимум 30 зображень. Фото проходять той самий перегляд, що й вебзавантаження. Для публікації потрібні назва, адреса, країна, тип нерухомості, щонайменше одне схвалене фото та право на публікацію. Оголошення агентств підпорядковуються наявним правилам видимості агентства; для особистих оголошень потрібна активна публікація, придбана в обліковому записі Doomio. Промоційні пропозиції зберігають свої наявні ліміти та підтвердження прав. API-ключі не купують плани або соціальне просування.

Перевірте publiclyVisible, status і photoReviewError у відповіді. Прострочене оголошення або невдалий перегляд фото не є публічно видимими. DELETE переводить оголошення назад у чернетку; при цьому зберігаються його ідентифікатор і історія. Видалення останнього фото також знімає оголошення.

Endpoints

Поля та відповіді

Дозволені поля для запису: title, description, sourceLocale, type, transactionType, price, currency, country, address, city, postalCode, latitude, longitude, rooms, bedrooms, bathrooms, usableArea, landArea, contactEmail, contactPhone. externalId призначається під час створення. Невідомі поля повертають 422. Дивіться OpenAPI для точних меж і підтримуваних країн/мов. Ціни подаються як десяткові рядки, площі — у квадратних метрах, координати — числові WGS84. Валюти: CZK, EUR, USD, GBP, PLN. Типи: apartment, house, land, commercial, other, development. Транзакції: sale, rent.

Списки повертають {"data": [...], "pagination": {"limit": 50, "nextAfter": 123}}. Повторюйте з ?after=123; nextAfter: null означає кінець. Ви можете отримати оголошення з CRM за допомогою ?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"}'

Необов’язковий If-Match у PATCH, publish, withdraw та операціях із зображеннями запобігає заміні оголошення, зміненого після вашого останнього GET. Невідповідність повертає 412; отримайте оголошення та розв’яжіть конфлікт. Максимальний JSON-запит: 128 KiB. Ліміт: 120 автентифікованих запитів на хвилину на обліковий запис/агентство сумарно для всіх його ключів; надлишкові запити повертають 429 і Retry-After: 60. Перевіряйте X-RateLimit-Remaining. Доступ із браузера через cross-origin не потрібен: інтеграції мають працювати на вашому сервері.

Для помилок використовується {"error":{"code":"validation_failed","message":"..."}}. Стани: 400 malformed request, 401 missing/invalid/expired key, 403 read-only key or publication entitlement missing, 404 listing/image outside your scope or absent, 405 method, 409 duplicate externalId, 412 stale ETag, 413 oversized upload/body, 415 Content-Type, 422 invalid fields/photo/publishing validation, 429 rate limit, 500 temporary server error. Кожна відповідь містить X-Request-ID; надавайте його під час повідомлення про помилку, а не свій секретний ключ.

Встановіть client

Потрібен Python 3.10 або новіший, без сторонніх пакетів. Завантажте client і файл ключа .env, зберігайте обидва поза публічним вебкаталогом, а потім запустіть:

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 — це масив об’єктів оголошень у форматі створення. sync шукає зовнішні ідентифікатори, створює відсутні чернетки та оновлює наявні оголошення. Він не видаляє оголошення, відсутні у файлі, не завантажує фото автоматично і не публікує їх. Upload/publish/withdraw — це явні команди. Це універсальний клієнт інтеграції JSON; наявним CRM-продуктам і далі потрібне власне зіставлення полів або конектор.