GeckoAPI
Entrar Começar grátis

// docs

Chaves na Mão PLP

Extrai páginas de listagem imobiliária da Chaves na Mão para venda e aluguel. Aceita URL pública do PLP ou filtros amigáveis para montar a busca.

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": "chavesnamao.com.br",
  "type": "plp",
  "businessType": "sale",
  "city": "Curitiba",
  "state": "PR",
  "neighborhood": "Centro",
  "propertyTypes": [
    "apartment"
  ],
  "amenities": [
    "pool",
    "balcony"
  ],
  "bedrooms": [
    3
  ],
  "bathrooms": [
    2
  ],
  "parkingSpots": [
    1
  ],
  "priceMin": 500000,
  "priceMax": 900000,
  "areaMin": 80,
  "areaMax": 180,
  "sort": "price",
  "directOwner": true,
  "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

chavesnamao_com_br_plp

Auth

Bearer ou X-API-Key

chavesnamao_com_br_plp tools/call 
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "chavesnamao_com_br_plp",
    "arguments": {
      "businessType": "sale",
      "city": "Curitiba",
      "state": "PR",
      "neighborhood": "Centro",
      "propertyTypes": [
        "apartment"
      ],
      "amenities": [
        "pool",
        "balcony"
      ],
      "bedrooms": [
        3
      ],
      "bathrooms": [
        2
      ],
      "parkingSpots": [
        1
      ],
      "priceMin": 500000,
      "priceMax": 900000,
      "areaMin": 80,
      "areaMax": 180,
      "sort": "price",
      "directOwner": true,
      "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 pública de PLP no domínio chavesnamao.com.br. Quando omitida, a API monta a rota base a partir de businessType/location. - https://www.mercadolivre.com.br/p/MLB123456
city
Cidade usada em Webmotors PLP e opcionalmente em Catho PLP (deve vir em par com state).
 string Opcional Cidade da busca. Se enviada, state também é obrigatório. - Sao Paulo
neighborhood
Bairro usado na Chaves na Mão PLP. Requer city + state quando enviado.
 string Opcional Bairro da busca. Requer city e state. - Centro
state
UF usada em Webmotors PLP e opcionalmente em Catho PLP (deve vir em par com city).
 string (UF 2 letras) Opcional UF de 2 letras. Pode ser usada sozinha (busca por estado) ou junto com city. - SP
businessType
Tipo de negócio usado no Zapimoveis PLP para escolher entre venda (sale) e aluguel (rent).
 "sale" | "rent" Condicional Obrigatório quando url não for enviado. Valores: sale ou rent. - sale
bedrooms
Filtro de quartos no Zapimoveis PLP. Aceita lista de inteiros (ex: [2,3,4]).
 integer[] Opcional Filtro de quartos. Para Chaves na Mão o backend aceita um único valor por request. - [2,3,4]
bathrooms
Filtro de banheiros no Zapimoveis PLP. Aceita lista de inteiros (ex: [2,3,4]).
 integer[] Opcional Filtro de banheiros. Para Chaves na Mão o backend aceita um único valor por request. - [2,3,4]
parkingSpots
Filtro de vagas no Zapimoveis PLP. Aceita lista de inteiros (ex: [2,3,4]).
 integer[] Opcional Filtro de vagas. Para Chaves na Mão o backend aceita um único valor por request. - [2,3,4]
propertyTypes
Tipos de imóvel para Chaves na Mão PLP. Aceita aliases amigáveis como apartment, house, penthouse, land, commercial_room e loft.
 array<string | integer> Opcional Lista de tipos de imóvel. Aliases amigáveis aceitos: apartment, house, penthouse, land, commercial_room, loft, flat, farm etc. - ["apartment", "house"]
amenities
Amenidades para Chaves na Mão PLP. Aliases confirmados: pool, balcony, garden, furnished e backyard.
 array<string | integer> Opcional Lista de amenidades. Aliases confirmados: pool, balcony, garden, furnished e backyard. IDs numéricos também são aceitos. - ["pool", "balcony"]
directOwner
Filtro de anunciante direto/particular na Chaves na Mão PLP.
 boolean Opcional Quando true, aplica o filtro de anunciante direto/particular. - true
condominium
Filtro para imóveis em condomínio na Chaves na Mão PLP.
 boolean Opcional Quando true, aplica o filtro de condomínio. - true
includeLaunches
Quando true, mantém lançamentos / newEnterprise na Chaves na Mão PLP. O default do worker é false.
 boolean Opcional Quando true, mantém lançamentos / newEnterprise na resposta. O default do worker é false. - false
priceMin
Preço mínimo para busca no Zapimoveis PLP.
 integer Opcional Preço mínimo. Inteiro >= 0. - 1000
priceMax
Preço máximo para busca no Zapimoveis PLP.
 integer Opcional Preço máximo. Inteiro >= 0 e >= priceMin. - 2000
areaMin
Área mínima (m²) para busca no Zapimoveis PLP.
 integer Opcional Área mínima em m². Inteiro >= 0. - 80
areaMax
Área máxima (m²) para busca no Zapimoveis PLP.
 integer Opcional Área máxima em m². Inteiro >= 0 e >= areaMin. - 220
sort
Ordenacao para OLX PLP, Booking Review e Hoteis Review. 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" | "price_relevance" | "most_relevant" | "newest_first" | "oldest_first" | "score_desc" | "score_asc" Opcional Ordenação suportada: relevance, price ou biggest_price. - date
target
Fonte alvo da extração.
 enum Obrigatório Sempre obrigatório e deve ser chavesnamao.com.br. - mercadolivre.com.br
type
Tipo da extração: pdp, idp, plp, quote, review ou places.
 enum Obrigatório Sempre obrigatório e deve ser plp. - pdp
page
Paginacao. Em PLP inicia em 1; em review (MercadoLivre, Booking e Hoteis) inicia em 0.
 integer Opcional Paginação 1-based. 1 2

Exemplos de request

PLP por filtros amigáveis

Fluxo recomendado: envie businessType, localização e filtros opcionais. O worker valida a página pública e consulta o endpoint interno de listagem.

PLP por filtros amigáveis 
{
  "target": "chavesnamao.com.br",
  "type": "plp",
  "businessType": "sale",
  "city": "Curitiba",
  "state": "PR",
  "neighborhood": "Centro",
  "propertyTypes": [
    "apartment"
  ],
  "amenities": [
    "pool",
    "balcony"
  ],
  "bedrooms": [
    3
  ],
  "bathrooms": [
    2
  ],
  "parkingSpots": [
    1
  ],
  "priceMin": 500000,
  "priceMax": 900000,
  "areaMin": 80,
  "areaMax": 180,
  "sort": "price",
  "directOwner": true,
  "page": 1
}

PLP por URL pública

Use a URL pública quando quiser preservar exatamente uma rota da Chaves na Mão. page ainda pode ser enviada para trocar de página.

PLP por URL pública 
{
  "target": "chavesnamao.com.br",
  "type": "plp",
  "url": "https://www.chavesnamao.com.br/apartamentos-a-venda/pr-curitiba/",
  "page": 1
}

Schema de response (leaf paths)

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

responseSchema 
{
  "source": "\"chavesnamao.com.br\"",
  "type": "\"plp\"",
  "parser": "\"realestate_listing_api\"",
  "url": "string",
  "requestUrl": "string",
  "apiUrl": "string",
  "extractedAt": "string (ISO datetime)",
  "title": "string | null",
  "description": "string | null",
  "headingTitle": "string | null",
  "businessType": "\"sale\" | \"rent\" | null",
  "page": "integer",
  "totalPages": "integer | null",
  "totalResults": "integer | null",
  "primaryResults": "integer",
  "nextPage": "integer | null",
  "nextPageUrl": "string | null",
  "includeLaunches": "boolean",
  "launchesFilteredOut": "integer",
  "filters": "object | null",
  "locations": "array<object>",
  "items": "array<object>"
}

Exemplo de response

responseExample 
{
  "source": "chavesnamao.com.br",
  "type": "plp",
  "parser": "realestate_listing_api",
  "url": "https://www.chavesnamao.com.br/apartamentos-a-venda/pr-curitiba/",
  "requestUrl": "https://www.chavesnamao.com.br/apartamentos-a-venda/pr-curitiba/",
  "apiUrl": "https://www.chavesnamao.com.br/api/realestate/listing/items/?viewport=desktop&level1=apartamentos-a-venda&level2=pr-curitiba&pg=1",
  "extractedAt": "2026-04-14T14:25:00.000Z",
  "title": "Apartamentos à venda em Curitiba, PR",
  "description": "Busca de apartamentos à venda em Curitiba.",
  "headingTitle": "Apartamentos à venda em Curitiba",
  "businessType": "sale",
  "page": 1,
  "totalPages": 2206,
  "totalResults": 33083,
  "primaryResults": 12,
  "nextPage": 2,
  "nextPageUrl": "https://www.chavesnamao.com.br/apartamentos-a-venda/pr-curitiba/?pg=2",
  "includeLaunches": false,
  "launchesFilteredOut": 2,
  "filters": {
    "state": "PR",
    "city": "Curitiba",
    "neighborhood": "Centro",
    "propertyTypes": [
      {
        "id": 1,
        "key": "apartamentos",
        "label": "Apartamento",
        "saleSegment": "apartamentos-a-venda",
        "rentSegment": "apartamentos-para-alugar"
      }
    ],
    "amenities": [
      {
        "id": 5,
        "key": "pool",
        "label": "Piscina"
      },
      {
        "id": 13,
        "key": "balcony",
        "label": "Varanda"
      }
    ],
    "bedrooms": 3,
    "bathrooms": 2,
    "parkingSpots": 1,
    "priceMin": 500000,
    "priceMax": 900000,
    "areaMin": 80,
    "areaMax": 180,
    "sort": "price",
    "directOwner": true,
    "condominium": false,
    "raw": {
      "realtyTypeTransaction": "sell"
    }
  },
  "locations": [
    {
      "id": 6015,
      "name": "Curitiba",
      "slug": "pr-curitiba",
      "category": "city",
      "suffixLocation": "PR"
    }
  ],
  "items": [
    {
      "position": 1,
      "id": "31728852",
      "url": "https://www.chavesnamao.com.br/imovel/apartamento-a-venda-1-quarto-pr-curitiba-cajuru-38m2-RS250000/id-31728852/",
      "title": "Apartamento com 1 quarto à venda no Cajuru, Curitiba",
      "description": "Apartamento compacto à venda em Curitiba.",
      "reference": "V021",
      "category": "residential",
      "businessType": "sale",
      "transaction": "SELL",
      "realtyType": {
        "id": 1,
        "name": "Apartamento",
        "pluralName": "Apartamentos",
        "slug": "apartamentos",
        "prefix": "deste"
      },
      "prices": {
        "main": "R$ 250.000",
        "rawPrice": 250000,
        "maxPrice": 250000,
        "condominiumFee": 0,
        "iptuValue": 0
      },
      "area": {
        "useful": 38,
        "usefulMax": 38,
        "total": 38,
        "totalMax": 38
      },
      "counts": {
        "bedrooms": {
          "count": 1,
          "max": 1
        },
        "bathrooms": {
          "count": 1,
          "max": 1
        },
        "suites": {
          "count": 0,
          "max": 0
        },
        "garages": {
          "count": 0,
          "max": 0
        },
        "commercialRooms": {
          "count": 0,
          "max": 0
        }
      },
      "address": {
        "street": "Rua Exemplo, 123",
        "neighborhood": "Cajuru",
        "city": "Curitiba",
        "state": "PR",
        "zipCode": "82900-000",
        "addressComplement": "",
        "publicAddress": false,
        "latitude": -25.4493,
        "longitude": -49.2306
      },
      "advertiser": {
        "id": "13039",
        "name": "Prime Soho",
        "url": "https://www.chavesnamao.com.br/imobiliaria/prime-soho/id-13039/",
        "type": "PJ",
        "category": 0,
        "contractDate": "2024-07-30T03:00:00.000Z",
        "creci": "J-4321",
        "stockCount": 120,
        "logoUrl": "https://www.chavesnamao.com.br/imn/0850x0450/N/60/imoveis/logo-prime.png",
        "phones": {
          "cellphone": "(41) 99999-0000",
          "landline": "(41) 3333-2200",
          "commercial": "(41) 3333-2201",
          "public": true
        },
        "address": {
          "city": "Curitiba",
          "state": "PR"
        }
      },
      "images": [
        "https://www.chavesnamao.com.br/imn/0850x0450/N/60/imoveis/13039/31728852/pr-curitiba-apartamento-01.jpg"
      ],
      "featuredImage": "https://www.chavesnamao.com.br/imn/0850x0450/N/60/imoveis/13039/31728852/pr-curitiba-apartamento-01.jpg",
      "imageCount": 8,
      "privativeAmenities": [],
      "commonAmenities": [],
      "has360Tour": false,
      "videoUrl": "",
      "acceptTrade": true,
      "acceptTrades": true,
      "petFriendly": false,
      "highlighted": false,
      "active": true,
      "isLaunch": false,
      "launchStatus": "",
      "updatedAt": "2026-04-13T15:00:00.000Z",
      "status": "ACTIVE",
      "score": 7.9
    }
  ]
}

Referência completa de campos

Path Tipo Descrição Exemplo
apiUrl string URL do endpoint interno `/api/realestate/listing/items/` usado para extrair a listagem estruturada. https://www.chavesnamao.com.br/api/realestate/listing/items/?viewport=desktop&level1=apartamentos-a-venda&level2=pr-curitiba&pg=1
businessType "sale" | "rent" | null Tipo de negócio inferido/aplicado na busca: sale ou rent. sale
description string | null Descrição resumida da listagem quando disponível. Busca de apartamentos à venda em Curitiba.
extractedAt string (ISO datetime) Timestamp ISO UTC em que a extração foi concluída. 2026-04-14T14:25:00.000Z
filters object | null Bloco normalizado de filtros observados/aplicados na busca. {"state":"PR","city":"Curitiba","neighborhood":"Centro","propertyTypes":[{"id":1,"key":"apartamentos","label":"Apartamento","saleSegment":"apartamentos-a-venda","rentSegment":"apartamentos-para-alugar"}],"amenities":[{"id":5,"key":"pool","label":"Piscina"},{"id":13,"key":"balcony","label":"Varanda"}],"bedrooms":3,"bathrooms":2,"parkingSpots":1,"priceMin":500000,"priceMax":900000,"areaMin":80,"areaMax":180,"sort":"price","directOwner":true,"condominium":false,"raw":{"realtyTypeTransaction":"sell"}}
headingTitle string | null Título principal renderizado/normalizado para a busca. Apartamentos à venda em Curitiba
includeLaunches boolean Replica o comportamento do request. false remove itens `/lancamento/` da resposta final. false
items array<object> Lista de anúncios estruturados retornados para a página consultada. [{"position":1,"id":"31728852","url":"https://www.chavesnamao.com.br/imovel/apartamento-a-venda-1-quarto-pr-curitiba-cajuru-38m2-RS250000/id-31728852/","title":"Apartamento com 1 quarto à venda no Cajuru, Curitiba","description":"Apartamento compacto à venda em Curitiba.","reference":"V021","category":"residential","businessType":"sale","transaction":"SELL","realtyType":{"id":1,"name":"Apartamento","pluralName":"Apartamentos","slug":"apartamentos","prefix":"deste"},"prices":{"main":"R$ 250.000","rawPrice":250000,"maxPrice":250000,"condominiumFee":0,"iptuValue":0},"area":{"useful":38,"usefulMax":38,"total":38,"totalMax":38},"counts":{"bedrooms":{"count":1,"max":1},"bathrooms":{"count":1,"max":1},"suites":{"count":0,"max":0},"garages":{"count":0,"max":0},"commercialRooms":{"count":0,"max":0}},"address":{"street":"Rua Exemplo, 123","neighborhood":"Cajuru","city":"Curitiba","state":"PR","zipCode":"82900-000","addressComplement":"","publicAddress":false,"latitude":-25.4493,"longitude":-49.2306},"advertiser":{"id":"13039","name":"Prime Soho","url":"https://www.chavesnamao.com.br/imobiliaria/prime-soho/id-13039/","type":"PJ","category":0,"contractDate":"2024-07-30T03:00:00.000Z","creci":"J-4321","stockCount":120,"logoUrl":"https://www.chavesnamao.com.br/imn/0850x0450/N/60/imoveis/logo-prime.png","phones":{"cellphone":"(41) 99999-0000","landline":"(41) 3333-2200","commercial":"(41) 3333-2201","public":true},"address":{"city":"Curitiba","state":"PR"}},"images":["https://www.chavesnamao.com.br/imn/0850x0450/N/60/imoveis/13039/31728852/pr-curitiba-apartamento-01.jpg"],"featuredImage":"https://www.chavesnamao.com.br/imn/0850x0450/N/60/imoveis/13039/31728852/pr-curitiba-apartamento-01.jpg","imageCount":8,"privativeAmenities":[],"commonAmenities":[],"has360Tour":false,"videoUrl":"","acceptTrade":true,"acceptTrades":true,"petFriendly":false,"highlighted":false,"active":true,"isLaunch":false,"launchStatus":"","updatedAt":"2026-04-13T15:00:00.000Z","status":"ACTIVE","score":7.9}]
launchesFilteredOut integer Quantidade de lançamentos removidos pelo filtro `includeLaunches=false`. 2
locations array<object> Localizações normalizadas retornadas pelo payload da Chaves na Mão. [{"id":6015,"name":"Curitiba","slug":"pr-curitiba","category":"city","suffixLocation":"PR"}]
nextPage integer | null Número da próxima página quando houver. 2
nextPageUrl string | null URL pública da próxima página quando houver. https://www.chavesnamao.com.br/apartamentos-a-venda/pr-curitiba/?pg=2
page integer Página atual normalizada em base 1. 1
parser "realestate_listing_api" Parser interno usado pelo worker para o endpoint de listagem. realestate_listing_api
primaryResults integer Quantidade de itens primários retornados nesta página. 12
requestUrl string URL final resolvida para a página pública depois da validação. https://www.chavesnamao.com.br/apartamentos-a-venda/pr-curitiba/
source "chavesnamao.com.br" Identificador fixo da origem extraída. chavesnamao.com.br
title string | null Título retornado pelo payload da listagem quando disponível. Apartamentos à venda em Curitiba, PR
totalPages integer | null Total de páginas informado pelo endpoint interno. 2206
totalResults integer | null Total de resultados informado pelo endpoint interno. 33083
type "plp" Tipo de extração executada: plp. plp
url string URL pública efetiva do PLP usado na validação do endereço. https://www.chavesnamao.com.br/apartamentos-a-venda/pr-curitiba/

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.