API объявлений

Как получить доступ

1. 01

   Создайте профиль агентства

   Войдите и создайте профиль своего агентства. Это бесплатно и работает сразу.

2. 02

   Запросите доступ

   На вкладке «API» страницы агентства напишите, в какой системе вы ведёте объявления, и отправьте запрос.

3. 03

   Мы включаем API

   Мы рассматриваем запрос и отвечаем по e-mail. Когда API включён, на вкладке «API» можно создавать ключи.

4. 04

   Создайте ключ

   Владелец создаёт ключ и передаёт его тому, кто подключает вашу систему. Ключ показывается один раз.

Что API делает и чего не делает

• Он работает только с объявлениями вашего агентства: публикация, изменение, снятие и проверка состояния.
• В нём нет поиска, и он ничего не отдаёт о чужих объявлениях: ни других агентств, ни частных продавцов. Это не способ читать сайт.
• Ключ принадлежит агентству, а не человеку. Создаёт и отзывает ключи только владелец профиля, одновременно не больше 5.
• Ключ показывается один раз, Siia хранит только его отпечаток, и каждый ключ перестаёт работать через 365 дней.
• Личные токены со страницы «Доступ для ИИ» здесь не работают.

Запросы

Все адреса начинаются с https://siia.ee/api/agency/v1. В каждом запросе заголовок Authorization: Bearer <key>. Ответы в JSON.

PUT/listings/{external_id}

Публикует новое объявление или заменяет существующее. Тело запроса это одно объявление с полями JSON-фида; external_id это ваш собственный идентификатор, он указывается в адресе. Проверка сразу; адрес, фото и публикация в течение минуты.

DELETE/listings/{external_id}

Снимает объявление с сайта. Отправьте {"reason": "sold"}, если оно продано. Повторный PUT вернёт его.

GET/listings/{external_id}

Состояние одного объявления и результат последнего изменения, с причинами, если не получилось. Хранится 14 дней.

GET/listings

Объявления вашего агентства с external_id, сначала последние изменённые, по 100 на странице. Для следующей страницы передайте next_cursor как ?cursor=.

Примеры

Опубликовать или обновить объявление. В listing.json одно объявление:

curl -X PUT https://siia.ee/api/agency/v1/listings/KB-10231 \
  -H 'Authorization: Bearer YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d @listing.json

{
    "deal": "sale",
    "type": "apartment",
    "price": 189000,
    "address": {
        "county": "Harju maakond",
        "city": "Tallinn",
        "district": "Kalamaja",
        "street": "Vabriku",
        "house": "12",
        "unit": "5"
    },
    "coordinates": {
        "lat": 59.44731,
        "lng": 24.73142
    },
    "area": 54.3,
    "rooms": 2,
    "bedrooms": 1,
    "bathrooms": 1,
    "floor": 3,
    "floors_total": 5,
    "built_year": 1962,
    "renovated_year": 2021,
    "condition": "renovated",
    "energy_label": "C",
    "material": "stone",
    "balcony_area": 4.5,
    "features": [
        "balcony",
        "storage",
        "fibre"
    ],
    "headline": {
        "et": "Renoveeritud kahetoaline korter Kalamajas",
        "ru": "Двухкомнатная квартира после ремонта в Каламая",
        "en": "Renovated two-room apartment in Kalamaja"
    },
    "description": {
        "et": "Valgusküllane korter vaikse sisehoovi poole. Uus elektrisüsteem ja torustik, rõdu õhtupäikesega.\n\nTrammipeatus on kolme minuti kaugusel.",
        "ru": "Светлая квартира с окнами в тихий двор. Новая электрика и трубы, балкон на вечернее солнце.",
        "en": "A bright apartment facing a quiet courtyard. New wiring and plumbing, a balcony with evening sun."
    },
    "agent_email": "[email protected]",
    "photos": [
        "https://media.example.ee/listings/10231/01.jpg",
        "https://media.example.ee/listings/10231/02.jpg",
        "https://media.example.ee/listings/10231/03.jpg"
    ],
    "floor_plan": "https://media.example.ee/listings/10231/plan.png"
}

Объявление прошло проверку и публикуется:

{
    "external_id": "KB-10231",
    "state": "queued",
    "message": "Accepted. The listing is published or updated in a moment; read the result with GET on the same address.",
    "warnings": []
}

Не хватает обязательного поля. Ничего не изменено:

{
    "error": {
        "code": "invalid_listing",
        "message": "The listing was not accepted. Nothing was changed."
    },
    "problems": [
        {
            "level": "error",
            "code": "missing_price",
            "detail": null,
            "message": "Цена не указана или не является числом"
        }
    ]
}

Проверить результат:

curl https://siia.ee/api/agency/v1/listings/KB-10231 \
  -H 'Authorization: Bearer YOUR_KEY'

{
    "external_id": "KB-10231",
    "listing": {
        "external_id": "KB-10231",
        "status": "live",
        "is_public": true,
        "url": "https://siia.ee/homes/kalamaja-vabriku-12",
        "price": 189000,
        "updated_at": "2026-11-14T10:02:11+02:00"
    },
    "last_change": {
        "state": "done",
        "result": "created",
        "accepted_at": "2026-11-14T10:01:58+02:00",
        "finished_at": "2026-11-14T10:02:11+02:00"
    }
}

Объект продан:

curl -X DELETE https://siia.ee/api/agency/v1/listings/KB-10231 \
  -H 'Authorization: Bearer YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"reason": "sold"}'

Коды ответов

200

Готово, или вот то, что вы запросили.

202

Принято. Результат можно получить запросом GET.

400

Тело запроса не является одним объявлением в виде JSON-объекта.

401

Нет ключа; ключ неверный, отозван или истёк; или вместо ключа агентства прислан личный токен.

403

API для этого агентства не включён.

404

У вашего агентства нет объявления с таким external_id.

409

Siia сняла это объявление. Опубликовать его снова нельзя.

413

Объявление слишком большое. Присылайте фото ссылками.

422

Объявление не принято. В ответе перечислено, что исправить.

429

Слишком много запросов. Подождите столько секунд, сколько указано в Retry-After.

Правила и лимиты

• Поля, допустимые значения и проверки те же, что в фиде. На странице фида описано каждое поле.
• Фото передаются ссылками (только https), Siia скачивает их в том порядке, в каком вы их прислали.
• Не больше 120 запросов в минуту на ключ и 3000 изменений в час на агентство; 120 запросов в минуту с одного адреса.
• Тело запроса не больше 256 KB.
• У объявлений, введённых на Siia вручную, нет external_id, и API их никогда не трогает.