Envíe anuncios a Seeki mediante API.

Obtener una clave de API

El acceso a la API de importación de agencias requiere una suscripción de agencia Seeki activa. Cada suscripción incluye una clave API asociada a la cuenta de su agencia.

Suscríbase en la página Para Agentes para empezar.

Autenticación

Cada solicitud debe incluir su clave API como token Bearer en la cabecera Authorization.

Authorization: Bearer seeki_live_your_key_here

Las claves que comienzan por seeki_live_ son claves de producción. Las claves de staging comienzan por seeki_test_. No son intercambiables entre entornos.

Su primera importación

Envíe una solicitud POST a /v1/listings con un cuerpo JSON que contenga un array listings. Cada elemento representa una propiedad.

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 lote correcto devuelve HTTP 200 con los arrays accepted y rejected:

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

Estructura de la petición

El cuerpo de nivel superior es { listings: [...] }. Campos obligatorios por anuncio:

Consulte el esquema completo con todos los campos opcionales en la referencia interactiva de la API.

Estructura de la respuesta y errores

El endpoint /v1/listings siempre devuelve HTTP 200 OK siempre que la propia solicitud esté bien formada (JSON válido, cabecera de autenticación correcta, dentro de los límites de tamaño). Los fallos de anuncios individuales se reportan dentro del array rejected — no como códigos de error HTTP.

Cada elemento rechazado incluye external_id, error_code y un mensaje legible. Los errores a nivel de lote (autenticación incorrecta, payload demasiado grande) devuelven un estado HTTP distinto de 200 con un error_code de nivel superior.

Códigos de error

Los códigos de nivel de lote devuelven errores HTTP. Los códigos por elemento aparecen en el array rejected de una respuesta 200.

Idempotencia / reimportaciones

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, cada elemento de importación se asigna a un Cloudflare Workflow con el ID:

agency-{agency_id}-{external_id}

Caducidad de anuncios

Cada anuncio importado tiene un TTL de 60 días desde la importación correcta más reciente. Una vez que el TTL caduca, el anuncio se despublica automáticamente mediante un cron diario.

Para mantener un anuncio publicado indefinidamente, vuelva a importarlo (incluso con datos idénticos) antes de que se cumpla la ventana de 60 días. Se recomienda implementar una resincronización nocturna de sus anuncios activos.

Estado y reintento

Utilice GET /v1/import-items/{import_item_id}/status para consultar el estado de procesamiento de un único elemento. El import_item_id se devuelve en el array accepted de la respuesta POST original.

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

Si un elemento termina en estado INFRA_LOST o INFRA_QUEUE_REJECTED, vuelva a encolarlo sin reenviar el lote completo:

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

Límites

• →Tamaño del cuerpo: 25 MB como máximo por petición.
• →Elementos por petición: 5000 como máximo. Divida los lotes más grandes.
• →Hoy no se aplica ningún límite de QPS. Las ráfagas muy grandes pueden ser limitadas automáticamente; reparta las sincronizaciones de gran volumen entre varias solicitudes.

Pasar a producción

Existen dos entornos separados. Las claves API están limitadas al entorno — una clave de producción no funcionará en staging, y viceversa.

Todos los endpoints (/listings, /import-items/{id}/status, /import-items/{id}/retry) son idénticos en ambos entornos.