GeckoAPI
PT EN
Entrar Testar URL

// docs

Portal Zuk PLP — busca de leilões de imóveis

Busca e pagina imóveis em leilão no Portal Zuk. Aceita palavra-chave ou localização estruturada, modalidade/situação, tipo de imóvel, vendedor, ocupação, desconto, parcelamento, quartos, vagas, preço, área e ordenação.

Nota importante: alguns campos podem retornar null em produção, dependendo da página de origem. Nesta documentação, os exemplos de output são preenchidos intencionalmente com valores não nulos para facilitar integração.

Quando a entidade consultada não existe na origem, o extract e a tool MCP retornam 200 com data: null e notFound: true. Esse caso é tratado como resposta concluída, não como erro de servidor.

Chamada HTTP

cURL 
curl -X POST https://api.geckoapi.com.br/v1/extract \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
  "target": "portalzuk.com.br",
  "type": "plp",
  "state": "SP",
  "city": "São Paulo",
  "region": "capital",
  "neighborhood": "Centro",
  "propertyTypes": [
    "residential"
  ],
  "seller": "caixa-economica-federal",
  "occupancy": "vacant",
  "minDiscountPercent": 30,
  "installments": true,
  "bedrooms": [
    2
  ],
  "parkingSpots": [
    1
  ],
  "priceMin": 50000,
  "priceMax": 500000,
  "areaMin": 50,
  "areaMax": 300,
  "sort": "lowest_price",
  "page": 1
}'

Chamada MCP

A mesma seam também aparece no MCP hospedado como uma tool dedicada. Os argumentos reaproveitam os campos do extract, mas target e type já ficam fixos pela tool.

Ver guia completo do MCP

Endpoint

POST /v1/mcp

Tool name

portalzuk_com_br_plp

Auth

Bearer ou X-API-Key

portalzuk_com_br_plp tools/call 
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "portalzuk_com_br_plp",
    "arguments": {
      "state": "SP",
      "city": "São Paulo",
      "region": "capital",
      "neighborhood": "Centro",
      "propertyTypes": [
        "residential"
      ],
      "seller": "caixa-economica-federal",
      "occupancy": "vacant",
      "minDiscountPercent": 30,
      "installments": true,
      "bedrooms": [
        2
      ],
      "parkingSpots": [
        1
      ],
      "priceMin": 50000,
      "priceMax": 500000,
      "areaMin": 50,
      "areaMax": 300,
      "sort": "lowest_price",
      "page": 1,
      "executionId": "exec_example_123"
    }
  }
}

Possibilidades de input

Campos suportados nesta API do POST /v1/extract, com regras específicas de obrigatoriedade e condicionais.

Campo Tipo Status Regra Default Exemplo
url
URL alvo da extração. Para alguns PLPs pode ser omitida quando a API monta a URL a partir de outros campos.
 string (URL) Opcional URL HTTPS do Portal Zuk iniciada por /leilao-de-imoveis. Normalmente é mais simples usar os filtros estruturados. - https://www.mercadolivre.com.br/p/MLB123456
keyword
Palavra-chave para buscas PLP. Em Google Search ela representa a query enviada ao Google; em Booking PLP é obrigatória; em outros PLPs pode substituir a URL.
 string Opcional Busca livre. Não combine com state, city ou neighborhood. - iphone 15 pro max
region
Regiao textual para buscas OLX PLP (ex.: Regiao de Bauru e Marilia).
 string Opcional Segmento regional da rota, como capital ou interior. Requer city e state. - Regiao de Bauru e Marilia
city
Cidade usada em buscas estruturadas de imóveis e veículos e opcionalmente em Catho PLP. Em VivaReal, requer state.
 string Opcional Cidade da busca. Requer state. - Sao Paulo
neighborhood
Bairro usado na Chaves na Mão PLP e VivaReal PLP. Requer city + state quando enviado.
 string Opcional Bairro da busca. Requer city e state. - Centro
seller
Nome ou slug do vendedor/comitente para filtrar leilões de imóveis no Portal Zuk.
 string Opcional Nome ou slug do vendedor/comitente. O backend normaliza para o slug da rota. - caixa-economica-federal
occupancy
Situação de ocupação do imóvel na busca do Portal Zuk.
 "all" | "occupied" | "vacant" Opcional all, occupied ou vacant. all vacant
auctionType
Modalidade ou situação do leilão no Portal Zuk. Não deve ser combinada com localização estruturada quando diferente de all.
 "all" | "judicial" | "extrajudicial" | "fiduciary" | "proposals" | "upcoming" | "ended" Opcional all, judicial, extrajudicial, fiduciary, proposals, upcoming ou ended. Valores diferentes de all não podem ser combinados com localização. all judicial
minDiscountPercent
Desconto mínimo em relação à avaliação para buscas de imóveis no Portal Zuk.
 integer (0-100) Opcional Desconto mínimo em relação à avaliação, inteiro entre 0 e 100. - 30
installments
Quando true, limita a busca do Portal Zuk a imóveis que aceitam parcelamento.
 boolean Opcional Quando true, filtra imóveis que aceitam parcelamento. false true
state
UF usada em buscas estruturadas de imóveis e veículos e opcionalmente em Catho PLP.
 string (UF 2 letras) Opcional UF de 2 letras; pode ser usada sozinha ou junto com city. - SP
bedrooms
Filtro de quartos em buscas imobiliárias PLP. Aceita lista de inteiros (ex: [2,3,4]).
 integer[] Opcional Um único inteiro de 0 a 20 representando o mínimo de dormitórios. - [2,3,4]
parkingSpots
Filtro de vagas em buscas imobiliárias PLP. Aceita lista de inteiros (ex: [2,3,4]).
 integer[] Opcional Um único inteiro de 0 a 6 representando o mínimo de vagas. - [2,3,4]
propertyTypes
Tipos de imóvel para Chaves na Mão e VivaReal PLP. Aceita aliases amigáveis como apartment, house, penthouse, land, commercial_room e loft.
 array<string | integer> Opcional Um valor: all, residential, commercial, rural, land, house ou apartment. - ["apartment", "house"]
priceMin
Preço mínimo para buscas PLP de imóveis e veículos.
 integer Opcional Preço mínimo inteiro, maior ou igual a 0. - 1000
priceMax
Preço máximo para buscas PLP de imóveis e veículos.
 integer Opcional Preço máximo inteiro, maior ou igual a priceMin. - 2000
areaMin
Área mínima (m²) para buscas imobiliárias PLP.
 integer Opcional Área mínima em m², inteira e maior ou igual a 0. - 80
areaMax
Área máxima (m²) para buscas imobiliárias PLP.
 integer Opcional Área máxima em m², inteira e maior ou igual a areaMin. - 220
sort
Ordenacao para VivaReal, Chaves na Mão, OLX e Webmotors PLP, Booking Review e Hoteis Review. VivaReal: relevance/date/price/biggest_price/biggest_area. Webmotors: relevance/price/biggest_price/year_desc/mileage_asc. OLX: relevance/date/price/biggest_price/price_relevance. Booking/Hoteis Review: most_relevant/newest_first/oldest_first/score_desc/score_asc.
 "relevance" | "date" | "price" | "biggest_price" | "biggest_area" | "price_relevance" | "most_relevant" | "newest_first" | "oldest_first" | "score_desc" | "score_asc" | "year_desc" | "mileage_asc" Opcional auction_date, location, lowest_price, highest_price, newest ou biggest_discount. auction_date date
target
Fonte alvo da extração.
 enum Obrigatório Sempre portalzuk.com.br. - mercadolivre.com.br
type
Tipo da extração: pdp, idp, plp, ilp, quote, review ou places.
 enum Obrigatório Sempre plp. - pdp
page
Paginacao. Em PLP, inclusive Trivago, e no Reclame AQUI ILP inicia em 1; em review (MercadoLivre, Booking e Hoteis) inicia em 0. O Reclame AQUI ILP aceita ate a pagina 100.
 integer Opcional Página 1-based, de 1 a 100. Cada página retorna até 30 lotes. 1 2

Exemplos de request

Busca por localização com filtros

Use state sozinho ou combine state, city, neighborhood e region. O exemplo também mostra todos os filtros quantitativos disponíveis.

Busca por localização com filtros 
{
  "target": "portalzuk.com.br",
  "type": "plp",
  "state": "SP",
  "city": "São Paulo",
  "region": "capital",
  "neighborhood": "Centro",
  "propertyTypes": [
    "residential"
  ],
  "seller": "caixa-economica-federal",
  "occupancy": "vacant",
  "minDiscountPercent": 30,
  "installments": true,
  "bedrooms": [
    2
  ],
  "parkingSpots": [
    1
  ],
  "priceMin": 50000,
  "priceMax": 500000,
  "areaMin": 50,
  "areaMax": 300,
  "sort": "lowest_price",
  "page": 1
}

Busca livre por palavra-chave

keyword é um modo de busca próprio e não deve ser combinado com state, city ou neighborhood.

Busca livre por palavra-chave 
{
  "target": "portalzuk.com.br",
  "type": "plp",
  "keyword": "apartamento ribeirão preto",
  "propertyTypes": [
    "apartment"
  ],
  "sort": "biggest_discount",
  "page": 1
}

Busca por modalidade ou situação

auctionType aceita judicial, extrajudicial, fiduciary, proposals, upcoming e ended. Quando diferente de all, não combine com localização estruturada.

Busca por modalidade ou situação 
{
  "target": "portalzuk.com.br",
  "type": "plp",
  "auctionType": "judicial",
  "propertyTypes": [
    "commercial"
  ],
  "occupancy": "occupied",
  "sort": "auction_date",
  "page": 2
}

Rota pública avançada

Uma URL pública de /leilao-de-imoveis também pode ser enviada para preservar uma rota específica do site. page continua controlando a paginação.

Rota pública avançada 
{
  "target": "portalzuk.com.br",
  "type": "plp",
  "url": "https://www.portalzuk.com.br/leilao-de-imoveis/u/residenciais/sp?order=menor_valor",
  "page": 1
}

Schema de response (leaf paths)

Mapa de paths de saída com tipo esperado para esta API.

responseSchema 
{
  "source": "\"portalzuk.com.br\"",
  "type": "\"plp\"",
  "parser": "\"server_html\"",
  "requestUrl": "string (URL)",
  "extractedAt": "string (ISO datetime)",
  "query.propertyType": "string",
  "query.occupancy": "string",
  "query.sort": "string",
  "page": "integer",
  "pageSize": "integer",
  "totalResults": "integer",
  "returnedResults": "integer",
  "nextPage": "integer",
  "items[].auctionId": "integer",
  "items[].lotId": "integer",
  "items[].propertyType": "string",
  "items[].title": "string",
  "items[].url": "string (URL)",
  "items[].imageUrl": "string (URL)",
  "items[].currentPrice": "number",
  "items[].address.formatted": "string",
  "items[].address.city": "string",
  "items[].address.state": "string",
  "items[].auctionRounds[].label": "string",
  "items[].auctionRounds[].price": "number",
  "items[].auctionRounds[].date": "string (ISO datetime)",
  "items[].auctionRounds[].discountPercent": "number",
  "items[].metadata.discountPercent": "number",
  "items[].metadata.installmentCount": "integer",
  "items[].metadata.maxAreaM2": "number",
  "items[].metadata.bedrooms": "integer",
  "items[].metadata.parkingSpots": "integer",
  "items[].metadata.occupied": "boolean",
  "items[].metadata.judicial": "boolean",
  "items[].metadata.sellerSlug": "string"
}

Exemplo de response

responseExample 
{
  "source": "portalzuk.com.br",
  "type": "plp",
  "parser": "server_html",
  "url": "https://www.portalzuk.com.br/leilao-de-imoveis/u/residenciais/sp?order=menor_valor",
  "requestUrl": "https://www.portalzuk.com.br/leilao-de-imoveis/u/residenciais/sp?order=menor_valor",
  "extractedAt": "2026-07-15T12:00:00.000Z",
  "query": {
    "keyword": "",
    "state": "SP",
    "city": "",
    "neighborhood": "",
    "region": "",
    "propertyType": "residential",
    "seller": "",
    "occupancy": "all",
    "auctionType": "all",
    "minDiscountPercent": 0,
    "installments": false,
    "bedroomsMin": 0,
    "parkingSpotsMin": 0,
    "priceMin": 0,
    "priceMax": 500000,
    "areaMin": 0,
    "areaMax": 300,
    "sort": "lowest_price"
  },
  "page": 1,
  "pageSize": 30,
  "totalResults": 241,
  "returnedResults": 30,
  "nextPage": 2,
  "items": [
    {
      "position": 1,
      "auctionId": 36801,
      "lotId": 229571,
      "propertyType": "Apartamento",
      "title": "Apartamento à venda em leilão",
      "url": "https://www.portalzuk.com.br/imovel/sp/araraquara/solidariedade/avenida-marginal-do-corrego-dos-martins-445/36801-229571",
      "imageUrl": "https://static.portalzuk.com.br/imovel/listagem/229571.jpg",
      "partner": "Portal Zuk",
      "address": {
        "street": "Avenida Marginal do Córrego dos Martins, 445",
        "neighborhood": "Solidariedade",
        "city": "Araraquara",
        "state": "SP",
        "formatted": "Avenida Marginal do Córrego dos Martins, 445, Solidariedade, Araraquara, SP",
        "latitude": -21.7845,
        "longitude": -48.178,
        "coordinatePrecision": "APPROXIMATE"
      },
      "areas": [
        {
          "label": "Área útil",
          "valueM2": 48.2
        }
      ],
      "auctionRounds": [
        {
          "label": "1º Leilão",
          "price": 28609.55,
          "date": "2026-07-22T14:00:00.000Z",
          "dateLabel": "22/07/2026 às 14h",
          "discountPercent": 42,
          "ended": false
        }
      ],
      "currentPrice": 28609.55,
      "metadata": {
        "residential": true,
        "commercial": false,
        "rural": false,
        "land": false,
        "houseOrApartment": true,
        "discountPercent": 42,
        "installmentCount": 12,
        "listedValue": 28609.55,
        "maxAreaM2": 48.2,
        "usableAreaM2": 48.2,
        "privateAreaM2": 48.2,
        "builtAreaM2": 48.2,
        "landAreaM2": 48.2,
        "totalAreaM2": 48.2,
        "bathrooms": 1,
        "parkingSpots": 1,
        "bedrooms": 2,
        "occupied": false,
        "judicial": true,
        "acceptingProposal": false,
        "fiduciary": false,
        "sellerSlug": "caixa-economica-federal"
      }
    }
  ]
}

Referência completa de campos

Path Tipo Descrição Exemplo
extractedAt string (ISO datetime) Instante da extração. 2026-07-15T12:00:00.000Z
items[].address.city string Cidade do imóvel. Araraquara
items[].address.formatted string Endereço consolidado. Avenida Marginal do Córrego dos Martins, 445, Solidariedade, Araraquara, SP
items[].address.state string UF do imóvel. SP
items[].auctionId integer Identificador do leilão. 36801
items[].auctionRounds[].date string (ISO datetime) Data normalizada da rodada. 2026-07-22T14:00:00.000Z
items[].auctionRounds[].discountPercent number Desconto indicado na rodada. 42
items[].auctionRounds[].label string Nome da rodada. 1º Leilão
items[].auctionRounds[].price number Valor da rodada. 28609.55
items[].currentPrice number Valor vigente no card. 28609.55
items[].imageUrl string (URL) Imagem principal do card. https://static.portalzuk.com.br/imovel/listagem/229571.jpg
items[].lotId integer Identificador do lote/imóvel. 229571
items[].metadata.bedrooms integer Quantidade de dormitórios. 2
items[].metadata.discountPercent number Desconto em relação à avaliação. 42
items[].metadata.installmentCount integer Número de parcelas anunciado. 12
items[].metadata.judicial boolean Indica leilão judicial. true
items[].metadata.maxAreaM2 number Maior área identificada, em m². 48.2
items[].metadata.occupied boolean Indica se o imóvel está ocupado. false
items[].metadata.parkingSpots integer Quantidade de vagas. 1
items[].metadata.sellerSlug string Slug do vendedor/comitente. caixa-economica-federal
items[].propertyType string Tipo exibido do imóvel. Apartamento
items[].title string Título do card. Apartamento à venda em leilão
items[].url string (URL) URL pública do PDP. https://www.portalzuk.com.br/imovel/sp/araraquara/solidariedade/avenida-marginal-do-corrego-dos-martins-445/36801-229571
nextPage integer Próxima página quando existe. 2
page integer Página retornada. 1
pageSize integer Limite de lotes por página. 30
parser "server_html" Estratégia usada: HTML server-side sem renderização de navegador. server_html
query.occupancy string Filtro de ocupação normalizado. all
query.propertyType string Tipo de imóvel normalizado. residential
query.sort string Ordenação normalizada. lowest_price
requestUrl string (URL) URL pública efetivamente consultada no Portal Zuk. https://www.portalzuk.com.br/leilao-de-imoveis/u/residenciais/sp?order=menor_valor
returnedResults integer Quantidade de lotes nesta resposta. 30
source "portalzuk.com.br" Fonte normalizada da extração. portalzuk.com.br
totalResults integer Total encontrado pela fonte. 241
type "plp" Tipo PLP da seam. plp

Erros comuns

Respostas com notFound: true não entram nesta tabela, porque retornam sucesso HTTP 200.

Status errorCode Quando acontece
400 INVALID_PAYLOAD JSON inválido ou violação das regras de validação do payload.
401 UNAUTHORIZED Header Authorization ausente ou token/chave inválida.
402 INSUFFICIENT_CREDITS Saldo de créditos insuficiente para a API solicitada.
403 FORBIDDEN Usuário sem acesso ou API temporariamente desabilitada.
409 EXECUTION_CONFLICT executionId conflita com uma execução em estado incompatível.
429 RATE_LIMIT_EXCEEDED / TOO_MANY_INFLIGHT_REQUESTS Limite de taxa ou limite de requisições em voo excedido.
5xx UPSTREAM_TIMEOUT / UPSTREAM_HTTP_ERROR / WORKER_INVOCATION_FAILED / WORKER_FUNCTION_ERROR / WORKER_INVALID_RESPONSE / INTERNAL_ERROR Falha de servidor no worker, provider/proxy ou gateway. Nesses casos os créditos são estornados automaticamente.