Envie anúncios para o Seeki via API.

Obter uma chave de API

O acesso à API de Importação de Agência requer uma subscrição de agência Seeki ativa. Cada subscrição inclui uma chave de API com âmbito limitado à sua conta de agência.

Subscreva na página Para Agentes para começar.

Autenticação

Cada pedido deve incluir a sua chave de API como token Bearer no cabeçalho Authorization.

Authorization: Bearer seeki_live_your_key_here

As chaves que começam por seeki_live_ são chaves de produção. As chaves de staging começam por seeki_test_. Não são intercambiáveis entre ambientes.

A sua primeira importação

Envie um pedido POST para /v1/listings com um corpo JSON que contenha um array listings. Cada elemento representa um imóvel.

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

Um lote bem-sucedido devolve HTTP 200 com arrays accepted e rejected:

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

Estrutura do pedido

O corpo de nível superior é { listings: [...] }. Campos obrigatórios por anúncio:

Consulte o esquema completo com todos os campos opcionais em referência interativa da API.

Estrutura de resposta e erros

O endpoint /v1/listings devolve sempre HTTP 200 OK desde que o próprio pedido esteja bem formado (JSON válido, cabeçalho de autenticação correto, dentro dos limites de tamanho). As falhas de anúncios individuais são reportadas dentro do array rejected — não como códigos de erro HTTP.

Cada item rejeitado inclui external_id, error_code e uma mensagem legível por humanos. Os erros ao nível do lote (autenticação inválida, payload demasiado grande) devolvem um estado HTTP não-200 com um error_code de nível superior.

Códigos de erro

Os códigos ao nível do lote devolvem erros HTTP. Os códigos por item aparecem no array rejected de uma resposta 200.

Idempotência / reimportações

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 item de importação é mapeado para um Cloudflare Workflow com o ID:

agency-{agency_id}-{external_id}

Expiração de anúncios

Cada anúncio importado tem um TTL de 60 dias a partir da última importação bem-sucedida. Quando o TTL expira, o anúncio é automaticamente despublicado por um cron job diário.

Para manter um anúncio ativo indefinidamente, reimporte-o (mesmo com dados idênticos) antes do fim da janela de 60 dias. Implementar uma re-sincronização noturna dos seus anúncios ativos é o padrão recomendado.

Estado + nova tentativa

Utilize GET /v1/import-items/{import_item_id}/status para consultar o estado de processamento de um único item. O import_item_id é devolvido no array accepted da resposta 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"
}

Se um item terminar num estado INFRA_LOST ou INFRA_QUEUE_REJECTED, recoloque-o em fila sem reenviar o lote completo:

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

Limites

• →Tamanho do corpo: 25 MB máximo por pedido.
• →Itens por pedido: 5000 máximo. Divida lotes maiores.
• →Atualmente não é aplicado qualquer limite de QPS. Picos muito grandes podem ser limitados automaticamente; distribua sincronizações de grande volume por vários pedidos.

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.

Entrar em produção

Existem dois ambientes separados. As chaves de API têm âmbito por ambiente — uma chave de produção não funcionará em staging, e vice-versa.

Todos os endpoints (/listings, /import-items/{id}/status, /import-items/{id}/retry) são idênticos em ambos os ambientes.