Sludinājumu API

Kā iegūt piekļuvi

1. 01

   Izveidojiet aģentūras profilu

   Piesakieties un izveidojiet savas aģentūras profilu. Tas ir bez maksas un darbojas uzreiz.

2. 02

   Pieprasiet piekļuvi

   Aģentūras lapas cilnē API norādiet, kurā sistēmā glabājat sludinājumus, un nosūtiet pieprasījumu.

3. 03

   Mēs ieslēdzam API

   Mēs izskatām pieprasījumu un atbildam pa e-pastu. Kad API ir ieslēgts, cilnē API varat izveidot atslēgas.

4. 04

   Izveidojiet atslēgu

   Īpašnieks izveido atslēgu un nodod to tam, kurš pieslēdz jūsu sistēmu. Atslēga tiek parādīta vienu reizi.

Ko API dara un ko nedara

• Tas darbojas tikai ar jūsu aģentūras sludinājumiem: publicē, atjaunina, noņem un pārbauda tos.
• Tajā nav meklēšanas, un tas neatgriež neko par citu aģentūru vai privātpārdevēju sludinājumiem. Tas nav veids, kā lasīt vietni.
• Atslēga pieder aģentūrai, nevis personai. Atslēgas izveido un atsauc tikai profila īpašnieks, vienlaikus ne vairāk kā 5.
• Atslēga tiek parādīta vienu reizi, Siia glabā tikai tās nospiedumu, un katra atslēga pārstāj darboties pēc 365 dienām.
• Personīgie žetoni no lapas "AI piekļuve" šeit nedarbojas.

Pieprasījumi

Visas adreses sākas ar https://siia.ee/api/agency/v1. Katrā pieprasījumā ir galvene Authorization: Bearer <key>. Atbildes ir JSON formātā.

PUT/listings/{external_id}

Publicēt jaunu sludinājumu vai aizstāt esošu. Pieprasījuma saturs ir viens sludinājums ar JSON plūsmas laukiem, external_id ir jūsu pašu identifikators, un tas ir norādīts adresē. Pārbaude notiek uzreiz, adrese, fotoattēli un publicēšana seko minūtes laikā.

DELETE/listings/{external_id}

Noņemt sludinājumu no vietnes. Nosūtiet {"reason": "sold"}, ja tas ir pārdots. Atkārtoti nosūtot ar PUT, sludinājums atgriežas.

GET/listings/{external_id}

Viena sludinājuma stāvoklis un pēdējās izmaiņas rezultāts, ar iemesliem, ja tā neizdevās. Tiek glabāts 14 dienas.

GET/listings

Jūsu aģentūras sludinājumi ar external_id, jaunākās izmaiņas vispirms, 100 lapā. Nākamajai lapai nododiet next_cursor kā ?cursor=.

Piemēri

Publicēt vai atjaunināt sludinājumu. Failā listing.json ir viens sludinājums:

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

Sludinājums izturēja pārbaudes un tiek apstrādāts:

{
    "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ūkst kaut kas obligāts. Nekas netika mainīts:

{
    "error": {
        "code": "invalid_listing",
        "message": "The listing was not accepted. Nothing was changed."
    },
    "problems": [
        {
            "level": "error",
            "code": "missing_price",
            "detail": null,
            "message": "Cena nav norādīta vai nav skaitlis"
        }
    ]
}

Pārbaudīt rezultātu:

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

Mājoklis ir pārdots:

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

Atbilžu kodi

200

Izdarīts, vai arī šeit ir tas, ko pieprasījāt.

202

Pieņemts. Rezultātu nolasiet ar GET.

400

Pieprasījuma saturs nav viens sludinājums kā JSON objekts.

401

Nav atslēgas, atslēga ir nepareiza, atsaukta vai beigusies, vai aģentūras atslēgas vietā izmantots personīgais žetons.

403

Šai aģentūrai API nav ieslēgts.

404

Jūsu aģentūrai nav sludinājuma ar šādu external_id.

409

Siia ir noņēmusi šo sludinājumu. To nevar publicēt atkārtoti.

413

Sludinājums ir pārāk liels. Fotoattēlus sūtiet kā saites.

422

Sludinājums netika pieņemts. Atbildē ir norādīts, kas jālabo.

429

Pārāk daudz pieprasījumu. Pagaidiet Retry-After norādīto sekunžu skaitu.

Noteikumi un ierobežojumi

• Lauki, pieņemtās vērtības un pārbaudes ir tādas pašas kā plūsmā. Plūsmas lapā ir aprakstīts katrs lauks.
• Fotoattēli ir saites, kuras Siia lejupielādē (tikai https), tādā secībā, kādā tās nosūtāt.
• Ne vairāk kā 120 pieprasījumi minūtē uz atslēgu un 3000 izmaiņas stundā uz aģentūru, 120 pieprasījumi minūtē no vienas adreses.
• Pieprasījuma saturs nedrīkst pārsniegt 256 KB.
• Sludinājumiem, ko ievadījāt Siia portālā ar roku, nav external_id, un API tos nekad neskar.