Skelbimų API

Kaip gauti prieigą

1. 01

   Sukurkite agentūros profilį

   Prisijunkite ir sukurkite savo agentūros profilį. Tai nemokama ir veikia iš karto.

2. 02

   Paprašykite prieigos

   Agentūros puslapio skirtuke „API“ nurodykite, kokioje sistemoje laikote skelbimus, ir išsiųskite užklausą.

3. 03

   Įjungiame API

   Peržiūrime užklausą ir atsakome el. paštu. Kai API įjungtas, skirtuke „API“ galite kurti raktus.

4. 04

   Sukurkite raktą

   Savininkas sukuria raktą ir perduoda jį tam, kas jungia jūsų sistemą. Raktas parodomas vieną kartą.

Ką API daro ir ko nedaro

• Jis veikia tik su jūsų agentūros skelbimais: juos skelbia, atnaujina, šalina ir tikrina.
• Jame nėra paieškos, ir jis nieko negrąžina apie kitų agentūrų ar privačių pardavėjų skelbimus. Tai nėra būdas skaityti svetainę.
• Raktas priklauso agentūrai, ne žmogui. Raktus kuria ir atšaukia tik profilio savininkas, vienu metu ne daugiau kaip 5.
• Raktas parodomas vieną kartą, Siia saugo tik jo kontrolinį atspaudą, o kiekvienas raktas po 365 d. nustoja veikti.
• Asmeniniai prieigos raktai iš puslapio „DI prieiga“ čia neveikia.

Užklausos

Visi adresai prasideda https://siia.ee/api/agency/v1. Kiekvienoje užklausoje yra antraštė Authorization: Bearer <key>. Atsakymai pateikiami JSON formatu.

PUT/listings/{external_id}

Paskelbti naują skelbimą arba pakeisti esamą. Užklausos turinys yra vienas skelbimas su JSON duomenų srauto laukais; external_id yra jūsų paties identifikatorius, nurodomas adrese. Patikrinama iš karto; adresas, nuotraukos ir paskelbimas seka per minutę.

DELETE/listings/{external_id}

Pašalinti skelbimą iš svetainės. Jei jis parduotas, siųskite {"reason": "sold"}. Pakartotinai išsiuntus PUT, jis grįžta.

GET/listings/{external_id}

Vieno skelbimo būsena ir paskutinio pakeitimo rezultatas, su priežastimis, jei nepavyko. Saugoma 14 d.

GET/listings

Jūsų agentūros skelbimai, turintys external_id, pirmiausia naujausi pakeitimai, po 100 viename puslapyje. Kitam puslapiui perduokite next_cursor kaip ?cursor=.

Pavyzdžiai

Paskelbti arba atnaujinti skelbimą. listing.json yra vienas skelbimas:

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

Skelbimas praėjo patikrinimus ir yra kelyje:

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

Trūksta kažko privalomo. Niekas nepakeista:

{
    "error": {
        "code": "invalid_listing",
        "message": "The listing was not accepted. Nothing was changed."
    },
    "problems": [
        {
            "level": "error",
            "code": "missing_price",
            "detail": null,
            "message": "Kainos nėra arba ji nėra skaičius"
        }
    ]
}

Patikrinti rezultatą:

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

Būstas parduotas:

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

Atsakymų kodai

200

Atlikta arba štai tai, ko prašėte.

202

Priimta. Rezultatą perskaitykite su GET.

400

Užklausos turinys nėra vienas skelbimas kaip JSON objektas.

401

Nėra rakto, raktas neteisingas, atšauktas ar nebegaliojantis arba vietoj agentūros rakto naudojamas asmeninis prieigos raktas.

403

Šiai agentūrai API neįjungtas.

404

Jūsų agentūra neturi skelbimo su tokiu external_id.

409

Siia pašalino šį skelbimą. Jo paskelbti iš naujo negalima.

413

Skelbimas per didelis. Nuotraukas siųskite nuorodomis.

422

Skelbimas nepriimtas. Atsakyme nurodyta, ką pataisyti.

429

Per daug užklausų. Palaukite tiek sekundžių, kiek nurodyta Retry-After.

Taisyklės ir limitai

• Laukai, priimamos reikšmės ir patikrinimai tokie patys kaip duomenų sraute. Duomenų srauto puslapyje aprašytas kiekvienas laukas.
• Nuotraukos yra nuorodos, kurias Siia atsisiunčia (tik https), ta tvarka, kuria jas siunčiate.
• Ne daugiau kaip 120 užklausų per minutę vienam raktui ir 3000 pakeitimų per valandą vienai agentūrai; 120 užklausų per minutę vienam adresui.
• Užklausos turinys ne didesnis kaip 256 KB.
• Skelbimai, kuriuos įvedėte rankiniu būdu Siia platformoje, neturi external_id, ir API jų niekada neliečia.