NAJDO pre vývojárov

Inzeráty prichádzajú na NAJDO dvoma cestami. Obe sú otvorené pre každý realitný softvér a pre každú kanceláriu.

  • Import API v1 (push). Váš systém posiela zmeny inzerátov, keď nastanú. Je to odporúčaná cesta pre realitné softvéry a CRM.
  • Realsoft feed (pull). Portál si sťahuje export kancelárie v pravidelnom intervale. Podrobnosti sú na stránke Realsoft feed.

Ako získať kľúč

Napíšte na info@najdo.sk, ktorý softvér prevádzkujete a ktoré kancelárie budete posielať. Dostanete API kľúč (začína rene_) s vlastným namespace, napríklad rene. Váš inzerát s ID 608 sa na portáli vedie ako rene:608. Kľúč môže mať IP whitelist a dá sa kedykoľvek vymeniť.

Rýchly štart

  1. Stiahnite si číselníky (GET /codetables) a lokality (GET /locations). Sú verejné, bez kľúča, a sú aj na stránkach Číselníky a Lokality.
  2. Preložte svoje hodnoty na kódy portálu a obce na ID portálu. Toto robí váš systém.
  3. Pošlite skúšobnú dávku s ?dry_run=true. Prejde všetkými kontrolami vrátane databázy, ale nič sa nezapíše.
  4. Posielajte zmeny naostro. Raz za noc porovnajte svoju ponuku so zoznamom GET /listings.

Celá referencia s možnosťou vyskúšať volania je na stránke API referencia (OpenAPI 3.1: /api/import/v1/openapi.json).

Autentifikácia

Každé volanie /listings nesie kľúč v hlavičke Authorization: Bearer <kľúč>. Kľúč má rozsahy listings:write (posielanie dávok) a listings:read (zoznam inzerátov).

Skúšobná dávka
curl -X POST 'https://rene.portal.berdo.cloud/api/import/v1/listings?dry_run=true' \
  -H 'Authorization: Bearer rene_…' \
  -H 'Content-Type: application/json' \
  --data @batch.json

Dávka

Jedna požiadavka POST /listings nesie najviac 100 položiek. Položky sa spracujú v poradí, každá vo vlastnej transakcii, takže chyba jednej nezastaví ostatné.

  • upsert založí inzerát, alebo ho prepíše celým obsahom listing. Čo v ňom chýba, portál vymaže. Stiahnutý inzerát znova zverejní.
  • withdraw inzerát stiahne. Dôvod sold a rented ho označí ako predaný alebo prenajatý, ostatné dôvody ho archivujú. Stiahnutie inzerátu, ktorý portál nemá, vráti ok.
  • updated_at je čas zmeny vo vašom systéme. Položku so starším časom, než portál má, preskočí (outcome: stale). Dávku preto môžete poslať znova kedykoľvek, aj súbežne s inou.
  • supersedes prevezme inzerát, ktorý portál už má z feedu kancelárie: <host feedu bez www>:<číslo inzerátu>. Číslo je to isté ako v adrese inzerátu na webe kancelárie. Inzerát si ponechá adresu, históriu cien aj dopyty.
  • Kanceláriu, pobočku a makléra portál založí alebo aktualizuje sám. Kanceláriu, ktorú už má z feedu, nájde podľa webu alebo IČO a jej feed vypne.
  • Fotky sa stiahnu asynchrónne do niekoľkých minút, najviac 30 na inzerát. Kým nie sú všetky, prevzatý inzerát ukazuje pôvodné. Fotky z Realvia imgcache sa párujú podľa svojho ID, takže sa nesťahujú znova.
batch.json
{
  "version": 1,
  "items": [
    {
      "action": "upsert",
      "id": "608",
      "updated_at": "2026-10-06T12:28:44+02:00",
      "supersedes": "example-reality.sk:9946",
      "listing": {
        "availability": "available",
        "transaction": "sale",
        "category": "apartment_3_rooms",
        "title": "3-izbový byt s loggiou, Košice – Furča",
        "description": "Kompletne zariadený 3-izbový byt po rekonštrukcii.\n\nLoggia, pivnica, výťah.",
        "price": {
          "amount": 189000,
          "currency": "EUR",
          "unit": "total",
          "note": "vrátane provízie"
        },
        "areas": {
          "usable": 68,
          "built_up": null,
          "land": null
        },
        "rooms": 3,
        "bathrooms": 1,
        "floor": 4,
        "floors_total": 8,
        "year_built": 1985,
        "year_reconstructed": 2021,
        "location": {
          "municipality_id": 598682,
          "street": "Baštovanského",
          "street_number": "12",
          "zip": "040 22",
          "latitude": 48.73653,
          "longitude": 21.2812,
          "show_street": true
        },
        "condition": "fully_renovated",
        "ownership": "personal",
        "energy_rating": "c",
        "furnishing": "furnished",
        "position": "higher_floor",
        "equipment": [
          "loggia",
          "cellar",
          "elevator"
        ],
        "heating": [
          "central"
        ],
        "building_type": [
          "panel"
        ],
        "orientation": [
          "south",
          "east"
        ],
        "extras": {
          "loggia_count": 1,
          "loggia_area": 4.5,
          "cellar_area": 3
        },
        "images": [
          {
            "url": "https://www.example-reality.sk/imgcache/wt/-6ac406984179d5fc0c0c3c0c.jpg",
            "position": 0
          },
          {
            "url": "https://www.example-reality.sk/imgcache/wt/-6ac406994179d5fc0c0c3c0d.jpg",
            "position": 1
          }
        ],
        "external_url": "https://www.example-reality.sk/nehnutelnost/9946-3-izbovy-byt-kosice-furca",
        "broker": {
          "id": "41",
          "first_name": "Jana",
          "last_name": "Nováková",
          "email": "jana.novakova@example-reality.sk",
          "phone": "+421 900 123 456"
        },
        "branch": {
          "id": "7",
          "name": "Pobočka Košice",
          "email": "kosice@example-reality.sk",
          "phone": "+421 55 123 4567",
          "street": "Hlavná 1",
          "city": "Košice",
          "zip": "040 01"
        },
        "agency": {
          "id": "12",
          "name": "Example Reality",
          "company_no": "12345679",
          "email": "info@example-reality.sk",
          "phone": "+421 2 123 4567",
          "website": "https://www.example-reality.sk",
          "address": {
            "street": "Hlavná 1",
            "city": "Košice",
            "zip": "040 01"
          }
        }
      }
    },
    {
      "action": "withdraw",
      "id": "127",
      "updated_at": "2026-10-06T12:30:00+02:00",
      "reason": "sold"
    }
  ]
}

Odpoveď

Na spracovanú dávku portál odpovie 200 s výsledkom každej položky. result: ok znamená spracované, netreba posielať znova. result: error znamená, že sa nezapísalo nič a treba opraviť dáta.

200 OK
{
  "batch_id": "cm1x7q0lk0000a8f3z9c2d4e1",
  "dry_run": false,
  "items": [
    {
      "id": "608",
      "result": "ok",
      "outcome": "taken_over",
      "status": "PUBLISHED",
      "listing_url": "https://najdo.sk/nehnutelnost/3-izbovy-byt-s-loggiou-kosice-furca-example-reality-sk-9946",
      "agency": {
        "slug": "example-reality.sk",
        "match": "website"
      },
      "photos": {
        "queued": 2
      }
    },
    {
      "id": "127",
      "result": "ok",
      "outcome": "withdrawn",
      "status": "SOLD",
      "listing_url": "https://najdo.sk/nehnutelnost/2-izbovy-byt-presov-rene-127"
    }
  ],
  "summary": {
    "ok": 2,
    "error": 0
  }
}
Položka s chybami
{
  "id": "129",
  "result": "error",
  "errors": [
    {
      "path": "listing.location.municipality_id",
      "code": "unknown_location",
      "message": "Obec 999999 neexistuje (GET /locations?level=municipality)."
    },
    {
      "path": "listing.category",
      "code": "unknown_code",
      "message": "Neznámy kód „apartment_other“. Platné kódy sú v GET /codetables."
    }
  ]
}

Kódy chýb položky: invalid, required, unknown_code, unknown_location, too_long, out_of_range, supersedes_forbidden, supersedes_ambiguous. Varovania (položka je spracovaná): invalid_contact, invalid_company_no, unknown_field, too_many_images, supersedes_not_found, supersedes_ignored, blocked.

Odmietnutie požiadavky

Stav iný ako 2xx znamená, že sa nezapísalo nič. Výnimkou je 500 uprostred dávky, keď môžu byť prvé položky zapísané. Celú dávku vtedy pošlite znova; vďaka updated_at je to bezpečné.

401
{
  "error": {
    "code": "unauthorized",
    "message": "Chýba platný API kľúč (hlavička Authorization: Bearer <kľúč>)."
  }
}
StavKódKedy
400invalid_json, invalid_batch, unsupported_version, invalid_queryNečitateľné telo, zlý tvar dávky, iná verzia ako 1, zlý parameter.
401unauthorizedChýbajúci, neznámy, zrušený alebo expirovaný kľúč.
403forbidden_scope, forbidden_ipKľúč nemá rozsah, alebo neplatí z vašej IP adresy.
404not_foundInzerát alebo číselník neexistuje.
413batch_too_largeViac ako 100 položiek alebo telo nad 5 MB.
429rate_limitedPriveľa požiadaviek; počkajte toľko sekúnd, koľko je v hlavičke Retry-After.
500server_errorChyba portálu; pošlite dávku znova.

Všetky kódy: invalid_json, invalid_batch, unsupported_version, invalid_query, unauthorized, forbidden_scope, forbidden_ip, not_found, batch_too_large, rate_limited, server_error, unavailable.

Limity

  • 100 položiek a 5 MB na dávku.
  • 30 požiadaviek za minútu na kľúč. Dávky posielajte za sebou, kým dostávate 2xx; odporúčaný timeout je 60 s.
  • 30 fotiek na inzerát, každá najviac 10 MB (JPEG, PNG, WebP alebo GIF), 5 videí.
  • 120 požiadaviek za minútu z jednej adresy na verejné číselníky, lokality a špecifikáciu.

Verzovanie

Adresa nesie hlavnú verziu (/api/import/v1) a dávka pole "version": 1. V rámci v1 pribúdajú len nepovinné polia, nové kódy v číselníkoch a nové endpointy; neznáme pole portál ignoruje s varovaním. Nekompatibilná zmena dostane /api/import/v2 a v1 pobeží súbežne aspoň 6 mesiacov.

VerziaDátumZmeny
1.0.02026-10Prvá verzia: dávky upsert a withdraw, dry_run, supersedes, číselníky, lokality.

Kontakt

Otázky, kľúče a hlásenia chýb: info@najdo.sk. Pri chybe pošlite batch_id z odpovede; podľa neho dávku nájdeme v histórii importov.