API ogłoszeń

Jak uzyskać dostęp

1. 01

   Utwórz profil biura

   Zaloguj się i utwórz profil swojego biura. To nic nie kosztuje i działa od razu.

2. 02

   Poproś o dostęp

   W zakładce API na stronie biura napisz, w jakim systemie prowadzisz ogłoszenia, i wyślij prośbę.

3. 03

   Włączamy API

   Rozpatrujemy prośbę i odpowiadamy e-mailem. Gdy API jest włączone, w zakładce API możesz tworzyć klucze.

4. 04

   Utwórz klucz

   Właściciel tworzy klucz i przekazuje go osobie, która podłącza wasz system. Klucz jest pokazywany raz.

Co API robi, a czego nie

• Działa wyłącznie z ogłoszeniami twojego biura: publikuje, aktualizuje, zdejmuje i sprawdza je.
• Nie ma wyszukiwania i nie zwraca nic o ogłoszeniach innych biur ani prywatnych sprzedających. Nie służy do odczytywania strony.
• Klucz należy do biura, nie do osoby. Klucze tworzy i unieważnia tylko właściciel profilu, najwyżej 5 naraz.
• Klucz jest pokazywany raz, Siia przechowuje tylko jego odcisk, a każdy klucz przestaje działać po 365 dniach.
• Osobiste tokeny ze strony „Dostęp dla AI” tu nie działają.

Żądania

Wszystkie adresy zaczynają się od https://siia.ee/api/agency/v1. Każde żądanie zawiera nagłówek Authorization: Bearer <key>. Odpowiedzi są w formacie JSON.

PUT/listings/{external_id}

Opublikuj nowe ogłoszenie lub zastąp istniejące. Treść to jedno ogłoszenie z polami feedu JSON; external_id to twój własny identyfikator, który trafia do adresu. Sprawdzane od razu; adres, zdjęcia i publikacja następują w ciągu minuty.

DELETE/listings/{external_id}

Zdejmij ogłoszenie ze strony. Wyślij {"reason": "sold"}, jeśli zostało sprzedane. Ponowne wysłanie przez PUT przywraca je.

GET/listings/{external_id}

Stan jednego ogłoszenia i wynik ostatniej zmiany, z przyczynami, jeśli się nie powiodła. Przechowywane przez 14 dni.

GET/listings

Ogłoszenia twojego biura z external_id, od najnowszej zmiany, po 100 na stronę. Przekaż next_cursor jako ?cursor=, aby pobrać następną stronę.

Przykłady

Opublikuj lub zaktualizuj ogłoszenie. Plik listing.json zawiera jedno ogłoszenie:

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

Ogłoszenie przeszło kontrolę i jest w drodze:

{
    "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": []
}

Brakuje czegoś wymaganego. Nic nie zostało zmienione:

{
    "error": {
        "code": "invalid_listing",
        "message": "The listing was not accepted. Nothing was changed."
    },
    "problems": [
        {
            "level": "error",
            "code": "missing_price",
            "detail": null,
            "message": "Brak ceny lub cena nie jest liczbą"
        }
    ]
}

Sprawdź wynik:

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

Nieruchomość została sprzedana:

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

Kody odpowiedzi

200

Gotowe lub oto to, o co prosiłeś.

202

Przyjęte. Wynik odczytaj przez GET.

400

Treść nie jest jednym ogłoszeniem w postaci obiektu JSON.

401

Brak klucza, klucz błędny, unieważniony lub wygasły albo token osobisty zamiast klucza biura.

403

API nie jest włączone dla tego biura.

404

Twoje biuro nie ma ogłoszenia z tym external_id.

409

Siia zdjęła to ogłoszenie. Nie można go ponownie opublikować.

413

Ogłoszenie jest za duże. Wysyłaj zdjęcia jako linki.

422

Ogłoszenie nie zostało przyjęte. Odpowiedź wymienia, co poprawić.

429

Zbyt wiele żądań. Odczekaj liczbę sekund podaną w Retry-After.

Zasady i limity

• Pola, akceptowane wartości i kontrole są takie same jak w feedzie. Strona feedu opisuje każde pole.
• Zdjęcia to linki, które Siia pobiera (tylko https), w kolejności, w jakiej je wysyłasz.
• Najwyżej 120 żądań na minutę na klucz i 3000 zmian na godzinę na biuro; 120 żądań na minutę z jednego adresu.
• Treść żądania może mieć najwyżej 256 KB.
• Ogłoszenia wpisane ręcznie na Siia nie mają external_id i API nigdy ich nie zmienia.