Hirdetések feltöltése a Seekibe API-n keresztül.

API-kulcs igénylése

Az Ügynökségi Import API-hoz aktív Seeki ügynökségi előfizetés szükséges. Minden előfizetéshez egy, az ügynökségi fiókra hatókörözött API-kulcs jár.

Iratkozzon fel a Közvetítőknek oldalon a kezdéshez.

Hitelesítés

Minden kérésnek tartalmaznia kell az API-kulcsot Bearer tokenként az Authorization fejlécben.

Authorization: Bearer seeki_live_your_key_here

A seeki_live_ előtagú kulcsok éles kulcsok. A staging kulcsok seeki_test_ előtaggal kezdődnek. Környezetek között nem cserélhetők fel.

Az első importálás

Küldjön POST kérést a /v1/listings végpontra, JSON törzsben egy listings tömböt tartalmazva. Minden elem egy ingatlant képvisel.

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

Sikeres köteg esetén HTTP 200-as választ kap, accepted és rejected tömbökkel:

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

Kérés formátuma

A legfelső szintű törzs: { listings: [...] }. Hirdetésenként kötelező mezők:

A teljes sémát az összes opcionális mezővel az interaktív API-referenciában.

Válasz formátuma és hibák

A /v1/listings végpont mindig HTTP 200 OK választ ad vissza, ha a kérés maga jól formázott (érvényes JSON, helyes hitelesítési fejléc, méreten belül). Az egyes hirdetések hibái a rejected tömbben kerülnek jelentésre — nem HTTP-hibakódként.

Minden elutasított elem tartalmazza az external_id-t, error_code-ot és egy emberbarát üzenetet. Kötegszintű hibák (rossz hitelesítés, túl nagy payload) nem 200-as HTTP-státuszt adnak vissza egy legfelső szintű error_code-dal.

Hibakódok

A kötegszintű kódok HTTP-hibát adnak vissza. Az elemenkénti kódok egy 200-as válasz rejected tömbjében jelennek meg.

Idempotencia / újraimportálás

Azonos external_id-jű hirdetés újraküldése frissíti a meglévő rekordot — nem hoz létre másolatot. A hirdetés TTL-je minden sikeres importálásnál megújul.

Belsőleg minden importált elem egy Cloudflare Workflow-hoz kapcsolódik a következő azonosítóval:

agency-{agency_id}-{external_id}

Hirdetés lejárata

Minden importált hirdetésnek 60 napos TTL-je van a legutóbbi sikeres importálástól számítva. A TTL lejárta után a hirdetést egy napi cron-feladat automatikusan közzétételből visszavonja.

Ha egy hirdetést határozatlan ideig élőn kíván tartani, importálja újra (akár azonos adatokkal) a 60 napos ablak lezárása előtt. Az ajánlott minta az aktív hirdetések nightly újraszinkronizálása.

Státusz és újrapróbálás

Használja a GET /v1/import-items/{import_item_id}/status végpontot egyetlen elem feldolgozási állapotának lekérdezéséhez. Az import_item_id az eredeti POST-válasz accepted tömbjében szerepel.

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

Ha egy elem INFRA_LOST vagy INFRA_QUEUE_REJECTED állapotba kerül, a teljes köteg újraküldése nélkül állítsa újra sorba:

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

Korlátok

• →Törzsméret: kérésenként legfeljebb 25 MB.
• →Kérésenként legfeljebb 5 000 elem. Nagyobb kötegeket osszon szét.
• →Jelenleg nincs QPS-korlát érvényes. Nagyon nagy löketszerű terhelés esetén automatikus sebességkorlátozás léphet érvénybe; a nagy volumenű szinkronizálásokat terítse szét több kérés között.

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.

Élesítés

Két külön környezet áll rendelkezésre. Az API-kulcsok környezethez kötöttek — egy éles kulcs nem működik staging-en, és fordítva.

Minden végpont (/listings, /import-items/{id}/status, /import-items/{id}/retry) azonos mindkét környezetben.