Базовый 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 megapixels на изображение, максимум 30 изображений. Фотографии проходят ту же проверку, что и загрузки через сайт. Для публикации требуются название, адрес, страна, тип объекта, как минимум одна одобренная фотография и право на публикацию. Объявления агентств следуют существующим правилам видимости для агентств; для личных объявлений нужна активная публикация, приобретенная в учетной записи Doomio. Промо-акции сохраняют свои существующие ограничения и подтверждение прав. API-ключи не покупают тарифы и не включают социальное продвижение.

Проверяйте publiclyVisible, status и photoReviewError в ответе. Истекшее объявление или фотография, не прошедшая проверку, не отображается публично. DELETE снимает объявление с публикации в черновик; при этом сохраняются его идентификатор и история. Удаление последней фотографии также снимает объявление с публикации.

Конечные точки

Поля и ответы

Записываемые поля: 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, публикации, снятии с публикации и операциях с изображениями предотвращает замену объявления, измененного после вашего последнего GET. Несовпадение возвращает 412; получите объявление и разрешите конфликт. Максимальный размер JSON-запроса: 128 KiB. Ограничение: 120 аутентифицированных запросов в минуту на учетную запись/агентство по всем его ключам; превышение возвращает 429 и Retry-After: 60. Проверьте X-RateLimit-Remaining. Кросс-доменный доступ из браузера не требуется: интеграции должны работать на вашем сервере.

Ошибки используют {"error":{"code":"validation_failed","message":"..."}}. Статусы: 400 — неверно сформированный запрос, 401 — отсутствующий/недействительный/истекший ключ, 403 — ключ только для чтения или отсутствует право на публикацию, 404 — объявление/изображение вне вашей области доступа или отсутствует, 405 — метод, 409 — дубликат externalId, 412 — устаревший ETag, 413 — слишком большой загрузочный файл/тело, 415 — Content-Type, 422 — недопустимые поля/проверка фотографии/валидации публикации, 429 — ограничение по частоте, 500 — временная ошибка сервера. В каждом ответе есть X-Request-ID; указывайте его при сообщении об ошибке, но никогда не указывайте свой секретный ключ.

Установка клиента

Требуется Python 3.10 или новее, без сторонних пакетов. Скачайте клиент и файл ключа .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-продуктам по-прежнему требуется собственное сопоставление полей или коннектор.