Zet advertenties in Seeki via API.

API-sleutel aanvragen

Toegang tot de Agency Import API vereist een actief Seeki agentschap-abonnement. Bij elk abonnement hoort één API-sleutel die is gekoppeld aan uw agentschap-account.

Abonneer u via de For Agents-pagina om te beginnen.

Authenticatie

Elke aanvraag moet uw API-sleutel als Bearer-token in de Authorization-header bevatten.

Authorization: Bearer seeki_live_your_key_here

Sleutels die beginnen met seeki_live_ zijn productiesleutels. Stagingsleutels beginnen met seeki_test_. Ze zijn niet uitwisselbaar tussen omgevingen.

Uw eerste import

Stuur een POST-aanvraag naar /v1/listings met een JSON-body die een listings-array bevat. Elk element vertegenwoordigt één pand.

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

Een geslaagde batch geeft HTTP 200 terug met accepted- en rejected-arrays:

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

Opbouw van verzoek

De top-level body is { listings: [...] }. Verplichte velden per advertentie:

Bekijk het volledige schema met alle optionele velden in de interactieve API-referentie.

Opbouw van respons en fouten

Het /v1/listings-endpoint geeft altijd HTTP 200 OK terug zolang de aanvraag zelf goed is opgebouwd (geldige JSON, juiste auth-header, binnen de groottelimieten). Fouten op individuele advertenties worden gerapporteerd in de rejected-array — niet als HTTP-foutcode.

Elk afgewezen item bevat external_id, error_code en een leesbaar bericht. Fouten op batchniveau (foute auth, te grote payload) geven een non-200 HTTP-status met een top-level error_code.

Foutcodes

Codes op batchniveau geven HTTP-fouten. Codes per item verschijnen in de rejected-array van een 200-respons.

Idempotentie / her-imports

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.

Intern wordt elk import-item gekoppeld aan een Cloudflare Workflow met de ID:

agency-{agency_id}-{external_id}

Verloop van advertentie

Elke geïmporteerde advertentie heeft een TTL van 60 dagen vanaf de meest recente geslaagde import. Zodra de TTL verloopt, wordt de advertentie automatisch offline gehaald door een dagelijkse cronjob.

Om een advertentie onbeperkt online te houden, importeert u hem opnieuw (zelfs met identieke data) vóór het einde van het venster van 60 dagen. Een nachtelijke re-sync van uw actieve advertenties implementeren is het aanbevolen patroon.

Status en opnieuw proberen

Gebruik GET /v1/import-items/{import_item_id}/status om de verwerkingsstatus van één item op te vragen. De import_item_id wordt teruggegeven in de accepted-array van de oorspronkelijke POST-respons.

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

Als een item in de status INFRA_LOST of INFRA_QUEUE_REJECTED terechtkomt, plaats het dan opnieuw in de wachtrij zonder de hele batch opnieuw in te dienen:

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

Limieten

• →Body-grootte: maximaal 25 MB per verzoek.
• →Items per verzoek: maximaal 5.000. Splits grotere batches.
• →Er geldt momenteel geen QPS-limiet. Zeer grote pieken kunnen automatisch worden afgeknepen; spreid grote synchronisaties over meerdere aanvragen.

Live gaan

Er zijn twee aparte omgevingen. API-sleutels zijn omgevingsspecifiek — een productiesleutel werkt niet op staging en omgekeerd.

Alle endpoints (/listings, /import-items/{id}/status, /import-items/{id}/retry) zijn identiek in beide omgevingen.