Ilmoitusrajapinta

Näin saat käyttöoikeuden

1. 01

   Luo välitystoimiston profiili

   Kirjaudu ja luo välitystoimistosi profiili. Se on maksutonta ja toimii heti.

2. 02

   Pyydä käyttöoikeutta

   Kerro välitystoimiston sivun API-välilehdellä, missä järjestelmässä säilytät ilmoituksiasi, ja lähetä pyyntö.

3. 03

   Otamme rajapinnan käyttöön

   Käymme pyynnön läpi ja vastaamme sähköpostitse. Kun rajapinta on käytössä, voit luoda avaimia API-välilehdellä.

4. 04

   Luo avain

   Omistaja luo avaimen ja antaa sen sille, joka yhdistää järjestelmänne. Avain näytetään kerran.

Mitä rajapinta tekee ja mitä ei

• Se toimii vain välitystoimistosi omien ilmoitusten kanssa: julkaise, päivitä, poista ja tarkista niitä.
• Siinä ei ole hakua, eikä se palauta mitään muiden välitystoimistojen tai yksityisten myyjien ilmoituksista. Se ei ole tapa lukea sivustoa.
• Avain kuuluu välitystoimistolle, ei henkilölle. Vain profiilin omistaja luo ja peruu avaimia, enintään 5 kerrallaan.
• Avain näytetään kerran, Siia säilyttää vain sen sormenjäljen, ja jokainen avain lakkaa toimimasta 365 päivän kuluttua.
• ”Tekoälyn käyttöoikeus” -sivun henkilökohtaiset tunnukset eivät toimi täällä.

Pyynnöt

Kaikki osoitteet alkavat https://siia.ee/api/agency/v1. Jokaisessa pyynnössä on otsake Authorization: Bearer <key>. Vastaukset ovat JSON-muodossa.

PUT/listings/{external_id}

Julkaise uusi ilmoitus tai korvaa olemassa oleva. Runko on yksi ilmoitus JSON-syötteen kentillä; external_id on oma tunnisteesi sille ja se tulee osoitteeseen. Tarkistetaan heti; osoite, kuvat ja julkaisu seuraavat minuutin kuluessa.

DELETE/listings/{external_id}

Poista ilmoitus sivustolta. Lähetä {"reason": "sold"}, kun kohde on myyty. Kun lähetät sen uudelleen PUT-pyynnöllä, se palaa.

GET/listings/{external_id}

Yhden ilmoituksen tila ja viimeisimmän muutoksen tulos syineen, jos se epäonnistui. Säilytetään 14 päivää.

GET/listings

Välitystoimistosi ilmoitukset, joilla on external_id, uusin muutos ensin, 100 sivulla. Anna next_cursor muodossa ?cursor= seuraavaa sivua varten.

Esimerkit

Julkaise tai päivitä ilmoitus. listing.json sisältää yhden ilmoituksen:

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

Ilmoitus läpäisi tarkistukset ja on matkalla:

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

Jotain pakollista puuttuu. Mitään ei muutettu:

{
    "error": {
        "code": "invalid_listing",
        "message": "The listing was not accepted. Nothing was changed."
    },
    "problems": [
        {
            "level": "error",
            "code": "missing_price",
            "detail": null,
            "message": "Hinta puuttuu tai ei ole luku"
        }
    ]
}

Tarkista tulos:

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

Koti myytiin:

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

Vastauskoodit

200

Valmis, tai tässä on pyytämäsi.

202

Hyväksytty. Lue tulos GET-pyynnöllä.

400

Runko ei ole yksi ilmoitus JSON-objektina.

401

Ei avainta, väärä, peruttu tai vanhentunut avain, tai henkilökohtainen tunnus välitystoimiston avaimen sijaan.

403

Rajapintaa ei ole otettu käyttöön tälle välitystoimistolle.

404

Välitystoimistollasi ei ole ilmoitusta tällä external_id-tunnisteella.

409

Siia on poistanut tämän ilmoituksen. Sitä ei voi julkaista uudelleen.

413

Ilmoitus on liian suuri. Lähetä kuvat linkkeinä.

422

Ilmoitusta ei hyväksytty. Vastauksessa luetellaan, mitä pitää korjata.

429

Liian monta pyyntöä. Odota Retry-After-otsakkeen ilmoittama määrä sekunteja.

Säännöt ja rajat

• Kentät, hyväksytyt arvot ja tarkistukset ovat samat kuin syötteessä. Syötesivulla kuvataan jokainen kenttä.
• Kuvat ovat linkkejä, jotka Siia lataa (vain https), siinä järjestyksessä kuin lähetät ne.
• Enintään 120 pyyntöä minuutissa avainta kohden ja 3000 muutosta tunnissa välitystoimistoa kohden; 120 pyyntöä minuutissa osoitetta kohden.
• Pyynnön runko on enintään 256 kt.
• Siiassa käsin kirjoittamillasi ilmoituksilla ei ole external_id-tunnistetta, eikä rajapinta koskaan koske niihin.