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.

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.