Inserisca annunci in Seeki tramite API.

Ottenere una chiave API

L'accesso all'API di importazione agenzia richiede un abbonamento agenzia Seeki attivo. Ogni abbonamento include una chiave API associata al suo account agenzia.

Si abboni nella pagina For Agents per iniziare.

Autenticazione

Ogni richiesta deve includere la sua chiave API come token Bearer nell'header Authorization.

Authorization: Bearer seeki_live_your_key_here

Le chiavi che iniziano con seeki_live_ sono chiavi di produzione. Le chiavi di staging iniziano con seeki_test_. Non sono interscambiabili tra ambienti.

La sua prima importazione

Invii una richiesta POST a /v1/listings con un corpo JSON contenente un array listings. Ogni elemento rappresenta un immobile.

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

Un batch elaborato con successo restituisce HTTP 200 con array accepted e rejected:

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

Struttura della richiesta

Il corpo di livello superiore è { listings: [...] }. Campi obbligatori per ciascun annuncio:

Vedi lo schema completo con tutti i campi facoltativi nella riferimento API interattivo.

Struttura della risposta ed errori

L'endpoint /v1/listings restituisce sempre HTTP 200 OK purché la richiesta stessa sia ben formata (JSON valido, header di autenticazione corretto, entro i limiti di dimensione). Gli errori dei singoli annunci sono riportati all'interno dell'array rejected — non come codici di errore HTTP.

Ogni elemento rifiutato include external_id, error_code e un messaggio leggibile. Gli errori a livello di batch (autenticazione errata, payload sovradimensionato) restituiscono uno stato HTTP diverso da 200 con un error_code di livello superiore.

Codici di errore

I codici a livello di batch restituiscono errori HTTP. I codici per singolo elemento appaiono nell'array rejected di una risposta 200.

Idempotenza / reimportazioni

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.

Internamente, ogni elemento importato è associato a un Cloudflare Workflow con l'ID:

agency-{agency_id}-{external_id}

Scadenza degli annunci

Ogni annuncio importato ha un TTL di 60 giorni dall'ultima importazione riuscita. Allo scadere del TTL, l'annuncio viene automaticamente rimosso dalla pubblicazione da un cron job giornaliero.

Per mantenere un annuncio attivo a tempo indeterminato, lo reimporti (anche con dati identici) prima della scadenza dei 60 giorni. Si consiglia di implementare una sincronizzazione notturna degli annunci attivi.

Stato + ritentativo

Utilizzi GET /v1/import-items/{import_item_id}/status per interrogare lo stato di elaborazione di un singolo elemento. L'import_item_id viene restituito nell'array accepted della risposta POST originale.

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

Se un elemento finisce in stato INFRA_LOST o INFRA_QUEUE_REJECTED, lo rimetta in coda senza inviare nuovamente l'intero batch:

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

Limiti

• →Dimensione del corpo: 25 MB massimo per richiesta.
• →Elementi per richiesta: 5.000 massimo. Suddivida i batch più grandi.
• →Attualmente non è applicato alcun limite QPS. Picchi molto elevati possono essere limitati automaticamente; distribuisca le sincronizzazioni ad alto volume su più richieste.

Passaggio in produzione

Esistono due ambienti separati. Le chiavi API hanno ambito limitato all'ambiente — una chiave di produzione non funzionerà in staging, e viceversa.

Tutti gli endpoint (/listings, /import-items/{id}/status, /import-items/{id}/retry) sono identici in entrambi gli ambienti.