Nahrávajte inzeráty do Seeki cez API.

Získať API kľúč

Prístup k Agency Import API vyžaduje aktívne predplatné agentúry Seeki. Súčasťou každého predplatného je jeden API kľúč viazaný na váš agentúrny účet.

Predplaťte si na stránke stránka Pre agentov a začnite.

Autentifikácia

Každá požiadavka musí obsahovať váš API kľúč ako Bearer token v hlavičke Authorization.

Authorization: Bearer seeki_live_your_key_here

Kľúče začínajúce na seeki_live_ sú produkčné. Staging kľúče začínajú na seeki_test_. Medzi prostrediami nie sú zameniteľné.

Váš prvý import

Pošlite POST požiadavku na /v1/listings s telom JSON obsahujúcim pole listings. Každý prvok predstavuje jednu nehnuteľnosť.

curl -X POST https://ingest.seeki.eu/v1/listings \
  -H "Authorization: Bearer seeki_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "listings": [
      {
        "external_id": "crm-listing-00123",
        "listing_type": "SELL",
        "real_estate_type": "APARTMENT",
        "price": 320000,
        "currency": "EUR",
        "address": {
          "street": "Wenceslas Square 1",
          "city": "Prague",
          "country_code": "CZ",
          "postal_code": "11000"
        },
        "name": "Sunny 2-bedroom apartment, Wenceslas Square",
        "floorage": 65
      }
    ]
  }'

Úspešná dávka vráti HTTP 200 s poliami accepted a rejected:

{
  "accepted": [
    { "external_id": "crm-listing-00123", "import_item_id": "uuid-…" }
  ],
  "rejected": []
}

Štruktúra požiadavky

Telo na najvyššej úrovni je { listings: [...] }. Povinné polia pre každý inzerát:

Kompletnú schému so všetkými voliteľnými poliami nájdete v interaktívna referencia API.

Štruktúra odpovede a chyby

Endpoint /v1/listings vždy vráti HTTP 200 OK, pokiaľ je samotná požiadavka správne sformovaná (platný JSON, správna autentifikačná hlavička, dodržané veľkostné limity). Zlyhania jednotlivých inzerátov sa hlásia v poli rejected — nie ako HTTP chybové kódy.

Každá zamietnutá položka obsahuje external_id, error_code a čitateľnú správu. Chyby na úrovni dávky (zlá autentifikácia, prekročená veľkosť) vrátia HTTP status iný ako 200 s poľom error_code na najvyššej úrovni.

Kódy chýb

Kódy na úrovni dávky vracajú HTTP chyby. Kódy pre jednotlivé položky sa objavujú v poli rejected odpovede 200.

Idempotencia / opakované importy

Re-posting a listing with the same external_id updates the existing record — it does not create a duplicate. The listing’s TTL is refreshed on every successful import.

Interne každá importovaná položka zodpovedá jednému Cloudflare Workflow s ID:

agency-{agency_id}-{external_id}

Expirácia inzerátu

Každý importovaný inzerát má TTL 60 dní od posledného úspešného importu. Po vypršaní TTL je inzerát automaticky stiahnutý zo zverejnenia denným cron jobom.

Ak chcete, aby bol inzerát zverejnený trvalo, znovu ho importujte (aj s identickými údajmi) pred uplynutím 60-dňového okna. Odporúčaným postupom je nočná opätovná synchronizácia vašich aktívnych inzerátov.

Stav a opakovanie

Použite GET /v1/import-items/{import_item_id}/status na zistenie stavu spracovania jednej položky. Hodnota import_item_id sa vracia v poli accepted v pôvodnej POST odpovedi.

curl https://ingest.seeki.eu/v1/import-items/{import_item_id}/status \
  -H "Authorization: Bearer seeki_live_your_key_here"

{
  "import_item_id": "uuid-…",
  "external_id": "crm-listing-00123",
  "status": "completed",
  "listing_id": "uuid-listing"
}

Ak položka skončí v stave INFRA_LOST alebo INFRA_QUEUE_REJECTED, znovu ju zaraďte do frontu bez opätovného odoslania celej dávky:

curl -X POST https://ingest.seeki.eu/v1/import-items/{import_item_id}/retry \
  -H "Authorization: Bearer seeki_live_your_key_here"

Limity

• →Veľkosť tela: maximálne 25 MB na požiadavku.
• →Položiek na požiadavku: maximálne 5 000. Väčšie dávky rozdeľte.
• →Aktuálne nie je vynútený žiadny limit QPS. Veľmi veľké nárazové prevádzky môžu byť automaticky obmedzené; objemné synchronizácie rozložte do viacerých požiadaviek.

OpenImmo XML / zip intake

OpenImmo is the de-facto real-estate exchange format for the DACH market (Germany, Austria, Switzerland) and is produced by every major CRM in those countries — FlowFact, onOffice, ImmoMaster, edomi, and others. If your CRM already exports OpenImmo, you can POST it directly without remapping fields into Seeki-JSON.

Two delivery flavours are accepted on the same endpoint, distinguished byContent-Type:

• →application/xml — raw OpenImmo XML, images referenced by absolute URL.
• →application/zip — bundle containing index.xml at the root plus the JPGs referenced from <anhang gruppe="INTERN"> nodes. We extract every referenced image, host it on Supabase Storage, and rewrite the listing’s media.images array before publication. Hosted images are removed when the listing expires (60-day default TTL); re-imports refresh them.

curl -X POST https://ingest.seeki.eu/v1/openimmo \
  -H "Authorization: Bearer seeki_live_your_key_here" \
  -H "Content-Type: application/xml" \
  --data-binary @export.xml

curl -X POST https://ingest.seeki.eu/v1/openimmo \
  -H "Authorization: Bearer seeki_live_your_key_here" \
  -H "Content-Type: application/zip" \
  --data-binary @export.zip

Target spec version: OpenImmo 1.2.x. Body cap: 200 MB. Bigger feeds get a 413 with a Suggested-Chunk-Size: 500 header — split index.xml into multiple POSTs of ≤500 listings each. Spec reference: openimmo.de.

The same per-item error codes from the JSON intake apply — only the request body format differs. Each <immobilie> that fails Zod validation appears in the response’s rejected array with a VALIDATION_FAILED code and the offending field path.

Idealista XML-ML intake

Idealista’s XML-ML (xmlGenerator) is the standard feed format on the Iberian peninsula — used by Idealista itself and the CRMs that export to it for the Spanish (ES) and Portuguese (PT) markets. Country is inferred per record from the <provincia> field; locale follows country.

Images are referenced by URL (<imagenes><imagen url="…"/>), so there is no zip flavour for this format — application/xml only. Listings without an accessible image URL are still accepted; only fields that fail Zod validation are rejected.

curl -X POST https://ingest.seeki.eu/v1/idealista \
  -H "Authorization: Bearer seeki_live_your_key_here" \
  -H "Content-Type: application/xml" \
  --data-binary @feed.xml

Target spec: Idealista xmlGenerator-1.X. The XML prolog encoding declaration is honoured — feeds shipped as windows-1252 are decoded correctly without manual conversion. Body cap: 200 MB. Spec reference: search Idealista’s help centre for “XML feed schema”.

Same per-item error codes as the JSON intake — see the table above.

Spustenie do produkcie

K dispozícii sú dve oddelené prostredia. API kľúče sú viazané na prostredie — produkčný kľúč nebude fungovať na stagingu a naopak.

Všetky endpointy (/listings, /import-items/{id}/status, /import-items/{id}/retry) sú v oboch prostrediach identické.