Kuulutuste API

Kuidas juurdepääsu saada

1. 01

   Looge büroo profiil

   Logige sisse ja looge oma büroo profiil. See on tasuta ja töötab kohe.

2. 02

   Taotlege juurdepääsu

   Kirjutage büroo lehe vahekaardil API, millises süsteemis kuulutusi hoiate, ja saatke taotlus.

3. 03

   Lülitame API sisse

   Vaatame taotluse läbi ja vastame e-postiga. Kui API on sees, saab vahekaardil API luua võtmeid.

4. 04

   Looge võti

   Omanik loob võtme ja annab selle sellele, kes teie süsteemi ühendab. Võtit näidatakse üks kord.

Mida API teeb ja mida mitte

• See töötab ainult teie büroo enda kuulutustega: avaldamine, muutmine, mahavõtmine ja oleku vaatamine.
• Sellel pole otsingut ja see ei näita teiste büroode ega eraisikute kuulutusi. See ei ole viis portaali sisu lugeda.
• Võti kuulub büroole, mitte inimesele. Võtmeid loob ja tühistab ainult profiili omanik, korraga kuni 5.
• Võtit näidatakse üks kord, Siia hoiab alles ainult selle sõrmejälje ja iga võti lakkab töötamast 365 päeva pärast.
• Isiklikud tokenid lehelt "Tehisintellekti ligipääs" siin ei tööta.

Päringud

Kõik aadressid algavad https://siia.ee/api/agency/v1. Igal päringul on päis Authorization: Bearer <key>. Vastused on JSON-is.

PUT/listings/{external_id}

Avaldab uue kuulutuse või asendab olemasoleva. Sisu on üks kuulutus JSON-voo väljadega; external_id on teie enda tunnus ja käib aadressi. Kontrollitakse kohe; aadress, fotod ja avaldamine järgnevad minuti jooksul.

DELETE/listings/{external_id}

Võtab kuulutuse lehelt maha. Saatke {"reason": "sold"}, kui see on müüdud. Uus PUT toob selle tagasi.

GET/listings/{external_id}

Ühe kuulutuse olek ja viimase muudatuse tulemus koos põhjustega, kui see ebaõnnestus. Säilib 14 päeva.

GET/listings

Teie büroo kuulutused, millel on external_id, uusim muudatus eespool, 100 lehel. Järgmise lehe jaoks saatke next_cursor kujul ?cursor=.

Näited

Kuulutuse avaldamine või muutmine. Failis listing.json on üks kuulutus:

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

Kuulutus läbis kontrolli ja on teel:

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

Midagi kohustuslikku on puudu. Midagi ei muudetud:

{
    "error": {
        "code": "invalid_listing",
        "message": "The listing was not accepted. Nothing was changed."
    },
    "problems": [
        {
            "level": "error",
            "code": "missing_price",
            "detail": null,
            "message": "Hind puudub või ei ole arv"
        }
    ]
}

Tulemuse vaatamine:

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

Kodu on müüdud:

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

Vastuse koodid

200

Tehtud või siin on küsitu.

202

Vastu võetud. Tulemuse saab GET-päringuga.

400

Sisu ei ole üks kuulutus JSON-objektina.

401

Võti puudub, on vale, tühistatud või aegunud või on büroo võtme asemel isiklik token.

403

API ei ole sellele büroole sisse lülitatud.

404

Teie bürool pole selle external_id-ga kuulutust.

409

Siia on selle kuulutuse eemaldanud. Seda ei saa uuesti avaldada.

413

Kuulutus on liiga suur. Saatke fotod linkidena.

422

Kuulutust ei võetud vastu. Vastuses on kirjas, mida parandada.

429

Liiga palju päringuid. Oodake Retry-After päises toodud sekundid.

Reeglid ja piirangud

• Väljad, lubatud väärtused ja kontrollid on samad mis voos. Voo lehel on iga väli kirjeldatud.
• Fotod on lingid, mille Siia alla laadib (ainult https), selles järjekorras, nagu need saadate.
• Kuni 120 päringut minutis võtme kohta ja 3000 muudatust tunnis büroo kohta; 120 päringut minutis aadressi kohta.
• Päringu sisu on kuni 256 KB.
• Siia portaalis käsitsi sisestatud kuulutustel pole external_id-d ja API neid kunagi ei puuduta.