// docs

Chaves na Mão PDP

Extrai dados detalhados de um anúncio imobiliário da Chaves na Mão usando a URL pública do imóvel.

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": "pdp",
  "url": "https://www.chavesnamao.com.br/imovel/apartamento-a-venda-4-quartos-com-garagem-sc-balneario-picarras-centro-496m2-RS5990000/id-29279133/"
}'

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_pdp

Auth

Bearer ou X-API-Key

chavesnamao_com_br_pdp tools/call

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "chavesnamao_com_br_pdp",
    "arguments": {
      "url": "https://www.chavesnamao.com.br/imovel/apartamento-a-venda-4-quartos-com-garagem-sc-balneario-picarras-centro-496m2-RS5990000/id-29279133/",
      "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)	Obrigatório	URL pública do anúncio no domínio chavesnamao.com.br. O worker extrai o listingId do segmento `/id-<numero>/`.	-	https://www.mercadolivre.com.br/p/MLB123456
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 pdp.	-	pdp

Exemplos de request

PDP por URL pública

Envie a URL pública do anúncio. O worker valida a página no domínio chavesnamao.com.br e resolve o listingId para o endpoint interno de detalhes.

PDP por URL pública

{
  "target": "chavesnamao.com.br",
  "type": "pdp",
  "url": "https://www.chavesnamao.com.br/imovel/apartamento-a-venda-4-quartos-com-garagem-sc-balneario-picarras-centro-496m2-RS5990000/id-29279133/"
}

Schema de response (leaf paths)

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

responseSchema

{
  "source": "\"chavesnamao.com.br\"",
  "type": "\"pdp\"",
  "parser": "\"realestate_details_api\"",
  "requestUrl": "string",
  "apiUrl": "string",
  "extractedAt": "string (ISO datetime)",
  "data": "object"
}

Exemplo de response

responseExample

{
  "source": "chavesnamao.com.br",
  "type": "pdp",
  "parser": "realestate_details_api",
  "requestUrl": "https://www.chavesnamao.com.br/imovel/apartamento-a-venda-4-quartos-com-garagem-sc-balneario-picarras-centro-496m2-RS5990000/id-29279133/",
  "apiUrl": "https://www.chavesnamao.com.br/api/realestate/details/?id=29279133",
  "extractedAt": "2026-04-14T14:30:00.000Z",
  "data": {
    "url": "https://www.chavesnamao.com.br/imovel/apartamento-a-venda-4-quartos-com-garagem-sc-balneario-picarras-centro-496m2-RS5990000/id-29279133/",
    "listingId": "29279133",
    "title": "Apartamento com 4 quartos à venda na Avenida Nereu Ramos, 2310, Centro, Balneário Piçarras",
    "metaTitle": "Apartamento em Balneário Piçarras",
    "metaDescription": "Descrição meta do imóvel.",
    "description": "Descrição completa do anúncio.",
    "reference": "RS5990000",
    "category": "residential",
    "businessType": "sale",
    "transaction": "SELL",
    "realtyType": {
      "id": 1,
      "name": "Apartamento",
      "pluralName": "Apartamentos",
      "slug": "apartamentos",
      "prefix": "deste"
    },
    "prices": {
      "main": "R$ 5.990.000",
      "rawPrice": 5990000,
      "maxPrice": 5990000,
      "condominiumFee": 0,
      "iptuValue": 0
    },
    "area": {
      "useful": 496,
      "usefulMax": 496,
      "total": 496,
      "totalMax": 496
    },
    "counts": {
      "bedrooms": {
        "count": 4,
        "max": 4
      },
      "bathrooms": {
        "count": 5,
        "max": 5
      },
      "suites": {
        "count": 2,
        "max": 2
      },
      "garages": {
        "count": 3,
        "max": 3
      },
      "commercialRooms": {
        "count": 0,
        "max": 0
      }
    },
    "address": {
      "street": "Avenida Nereu Ramos, 2310",
      "neighborhood": "Centro",
      "city": "Balneário Piçarras",
      "state": "SC",
      "zipCode": "88380-000",
      "addressComplement": "",
      "publicAddress": true,
      "latitude": -26.7403845,
      "longitude": -48.6810012
    },
    "advertiser": {
      "id": "602848",
      "name": "TOLENTINO IMÓVEIS",
      "url": "https://www.chavesnamao.com.br/imobiliaria/tolentino-imoveis/id-602848/",
      "type": "PJ",
      "category": 0,
      "contractDate": "2024-07-30T03:00:00.000Z",
      "creci": "J-0000",
      "stockCount": 48,
      "logoUrl": "https://www.chavesnamao.com.br/imn/0850x0450/N/60/imoveis/logo-tolentino.png",
      "phones": {
        "cellphone": "(47) 99999-0000",
        "landline": "(47) 3344-5500",
        "commercial": "(47) 3344-5501",
        "public": true
      },
      "address": {
        "city": "Balneário Piçarras",
        "state": "SC"
      }
    },
    "images": [
      "https://www.chavesnamao.com.br/imn/0850x0450/N/60/imoveis/602848/29279133/sc-balneario-picarras-centro-avenida-nereu-ramos-apartamento-a-venda-4-quartos-01.jpg"
    ],
    "featuredImage": "https://www.chavesnamao.com.br/imn/0850x0450/N/60/imoveis/602848/29279133/sc-balneario-picarras-centro-avenida-nereu-ramos-apartamento-a-venda-4-quartos-01.jpg",
    "imageCount": 15,
    "privativeAmenities": [
      "Varanda gourmet",
      "Churrasqueira"
    ],
    "commonAmenities": [
      "Piscina",
      "Academia"
    ],
    "proximities": {
      "schools": [
        "Escola Exemplo"
      ]
    },
    "gmb": {
      "totalReviews": 29,
      "rating": 5,
      "url": "https://www.google.com/maps?cid=123"
    },
    "media": {
      "videoUrl": "",
      "tour360": ""
    },
    "acceptTrade": true,
    "acceptTrades": true,
    "petFriendly": false,
    "highlighted": false,
    "active": true,
    "updatedAt": "2026-04-14T00:00:00.000Z",
    "status": "ACTIVE",
    "score": 9.3,
    "launchStatus": ""
  }
}

Referência completa de campos

Path	Tipo	Descrição	Exemplo
apiUrl	string	URL do endpoint interno `/api/realestate/details/` usado para obter o JSON estruturado do anúncio.	https://www.chavesnamao.com.br/api/realestate/details/?id=29279133
data	object	Payload detalhado normalizado do anúncio imobiliário.	{"url":"https://www.chavesnamao.com.br/imovel/apartamento-a-venda-4-quartos-com-garagem-sc-balneario-picarras-centro-496m2-RS5990000/id-29279133/","listingId":"29279133","title":"Apartamento com 4 quartos à venda na Avenida Nereu Ramos, 2310, Centro, Balneário Piçarras","metaTitle":"Apartamento em Balneário Piçarras","metaDescription":"Descrição meta do imóvel.","description":"Descrição completa do anúncio.","reference":"RS5990000","category":"residential","businessType":"sale","transaction":"SELL","realtyType":{"id":1,"name":"Apartamento","pluralName":"Apartamentos","slug":"apartamentos","prefix":"deste"},"prices":{"main":"R$ 5.990.000","rawPrice":5990000,"maxPrice":5990000,"condominiumFee":0,"iptuValue":0},"area":{"useful":496,"usefulMax":496,"total":496,"totalMax":496},"counts":{"bedrooms":{"count":4,"max":4},"bathrooms":{"count":5,"max":5},"suites":{"count":2,"max":2},"garages":{"count":3,"max":3},"commercialRooms":{"count":0,"max":0}},"address":{"street":"Avenida Nereu Ramos, 2310","neighborhood":"Centro","city":"Balneário Piçarras","state":"SC","zipCode":"88380-000","addressComplement":"","publicAddress":true,"latitude":-26.7403845,"longitude":-48.6810012},"advertiser":{"id":"602848","name":"TOLENTINO IMÓVEIS","url":"https://www.chavesnamao.com.br/imobiliaria/tolentino-imoveis/id-602848/","type":"PJ","category":0,"contractDate":"2024-07-30T03:00:00.000Z","creci":"J-0000","stockCount":48,"logoUrl":"https://www.chavesnamao.com.br/imn/0850x0450/N/60/imoveis/logo-tolentino.png","phones":{"cellphone":"(47) 99999-0000","landline":"(47) 3344-5500","commercial":"(47) 3344-5501","public":true},"address":{"city":"Balneário Piçarras","state":"SC"}},"images":["https://www.chavesnamao.com.br/imn/0850x0450/N/60/imoveis/602848/29279133/sc-balneario-picarras-centro-avenida-nereu-ramos-apartamento-a-venda-4-quartos-01.jpg"],"featuredImage":"https://www.chavesnamao.com.br/imn/0850x0450/N/60/imoveis/602848/29279133/sc-balneario-picarras-centro-avenida-nereu-ramos-apartamento-a-venda-4-quartos-01.jpg","imageCount":15,"privativeAmenities":["Varanda gourmet","Churrasqueira"],"commonAmenities":["Piscina","Academia"],"proximities":{"schools":["Escola Exemplo"]},"gmb":{"totalReviews":29,"rating":5,"url":"https://www.google.com/maps?cid=123"},"media":{"videoUrl":"","tour360":""},"acceptTrade":true,"acceptTrades":true,"petFriendly":false,"highlighted":false,"active":true,"updatedAt":"2026-04-14T00:00:00.000Z","status":"ACTIVE","score":9.3,"launchStatus":""}
extractedAt	string (ISO datetime)	Timestamp ISO UTC em que a extração foi concluída.	2026-04-14T14:30:00.000Z
parser	"realestate_details_api"	Parser interno usado pelo worker para o endpoint de detalhes.	realestate_details_api
requestUrl	string	URL pública validada no domínio da Chaves na Mão.	https://www.chavesnamao.com.br/imovel/apartamento-a-venda-4-quartos-com-garagem-sc-balneario-picarras-centro-496m2-RS5990000/id-29279133/
source	"chavesnamao.com.br"	Identificador fixo da origem extraída.	chavesnamao.com.br
type	"pdp"	Tipo de extração executada: pdp.	pdp

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.