// docs
Extrai uma página de imóvel em leilão do Portal Zuk com identificação do lote, endereço e coordenadas, fotos, ocupação, características, rodadas, valores, desconto, vendedor, matrícula, processo, visitação, pagamentos e documentos.
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.
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": "pdp",
"url": "https://www.portalzuk.com.br/imovel/sp/ribeirao-preto/residencial-greenville/rua-regina-aurea-barroso-reis-96/36784-229343"
}'
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.
Endpoint
POST /v1/mcp
Tool name
portalzuk_com_br_pdp
Auth
Bearer ou X-API-Key
{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "portalzuk_com_br_pdp",
"arguments": {
"url": "https://www.portalzuk.com.br/imovel/sp/ribeirao-preto/residencial-greenville/rua-regina-aurea-barroso-reis-96/36784-229343",
"executionId": "exec_example_123"
}
}
}
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 HTTPS do Portal Zuk sob /imovel/, terminando com os identificadores auctionId-lotId. | - | https://www.mercadolivre.com.br/p/MLB123456 |
| 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 pdp. | - | pdp |
Envie a URL pública retornada no campo items[].url do PLP. A URL deve estar em /imovel/ e terminar com auctionId-lotId.
{
"target": "portalzuk.com.br",
"type": "pdp",
"url": "https://www.portalzuk.com.br/imovel/sp/ribeirao-preto/residencial-greenville/rua-regina-aurea-barroso-reis-96/36784-229343"
}Mapa de paths de saída com tipo esperado para esta API.
{
"source": "\"portalzuk.com.br\"",
"type": "\"pdp\"",
"parser": "\"1.0.0\"",
"requestUrl": "string (URL)",
"canonicalUrl": "string (URL)",
"extractedAt": "string (ISO datetime)",
"auctionId": "integer",
"lotId": "integer",
"zukCode": "string",
"lotNumber": "string",
"title": "string",
"propertyType": "string",
"address.formatted": "string",
"address.city": "string",
"address.state": "string",
"address.latitude": "number",
"address.longitude": "number",
"images[]": "string (URL)",
"occupancyStatus": "string",
"occupied": "boolean",
"description": "string",
"observations": "string",
"visitation": "string",
"registration": "string",
"taxpayerId": "string",
"lawsuitNumber": "string",
"lawsuitUrl": "string (URL)",
"features[].label": "string",
"features[].value": "string",
"auctionType": "string",
"auctionRelationUrl": "string (URL)",
"participationUrl": "string (URL)",
"closingLabel": "string",
"auctionRounds[].label": "string",
"auctionRounds[].price": "number",
"auctionRounds[].date": "string (ISO datetime)",
"auctionRounds[].discountPercent": "number",
"minimumBid": "number",
"currentBid": "number",
"minimumIncrement": "number",
"discountPercent": "number",
"commissionPercent": "number",
"seller.name": "string",
"seller.slug": "string",
"paymentOptions[].label": "string",
"paymentOptions[].maxInstallments": "integer",
"installmentProposal": "string",
"documents[].label": "string",
"documents[].url": "string (URL)",
"documents[].requiresLogin": "boolean"
}{
"source": "portalzuk.com.br",
"type": "pdp",
"parser": "1.0.0",
"url": "https://www.portalzuk.com.br/imovel/sp/ribeirao-preto/residencial-greenville/rua-regina-aurea-barroso-reis-96/36784-229343",
"canonicalUrl": "https://www.portalzuk.com.br/imovel/sp/ribeirao-preto/residencial-greenville/rua-regina-aurea-barroso-reis-96/36784-229343",
"requestUrl": "https://www.portalzuk.com.br/imovel/sp/ribeirao-preto/residencial-greenville/rua-regina-aurea-barroso-reis-96/36784-229343",
"extractedAt": "2026-07-15T12:00:05.000Z",
"auctionId": 36784,
"lotId": 229343,
"zukCode": "ZUK229343",
"lotNumber": "1",
"title": "Casa à venda em leilão",
"propertyType": "Casa",
"metaTitle": "Casa em leilão em Ribeirão Preto",
"metaDescription": "Imóvel residencial disponível em leilão no Portal Zuk.",
"address": {
"formatted": "Rua Regina Aurea Barroso Reis, 96 - Residencial Greenville - Ribeirão Preto/SP",
"street": "Rua Regina Aurea Barroso Reis, 96",
"neighborhood": "Residencial Greenville",
"city": "Ribeirão Preto",
"state": "SP",
"latitude": -21.1767,
"longitude": -47.8208
},
"images": [
"https://static.portalzuk.com.br/imovel/detalhe/229343-1.jpg"
],
"occupancyStatus": "Imóvel desocupado",
"occupied": false,
"description": "Casa residencial com área construída, terreno e dependências descritas no edital.",
"observations": "Consulte o edital e os documentos antes de participar.",
"visitation": "Visitação mediante agendamento conforme as regras do leilão.",
"registration": "Matrícula 123456 do 1º Cartório de Registro de Imóveis. Nº Contribuinte: 1234567",
"taxpayerId": "1234567",
"lawsuitNumber": "1001234-56.2025.8.26.0000",
"lawsuitUrl": "https://www.portalzuk.com.br/documento/processo/229343",
"features": [
{
"label": "Área construída",
"value": "180,00 m²",
"numericValue": 180
}
],
"auctionType": "judicial",
"auctionRelationUrl": "https://www.portalzuk.com.br/leilao-de-imoveis/tl/residenciais/leilao-judicial",
"participationUrl": "https://www.portalzuk.com.br/participar/36784/229343",
"closingLabel": "Encerramento do leilão",
"auctionRounds": [
{
"label": "1º Leilão",
"price": 450000,
"date": "2026-07-22T14:00:00.000Z",
"dateLabel": "22/07/2026 às 14h",
"discountPercent": 25
}
],
"minimumBid": 450000,
"currentBid": 450000,
"minimumIncrement": 5000,
"discountPercent": 25,
"commissionPercent": 5,
"seller": {
"name": "Caixa Econômica Federal",
"url": "https://www.portalzuk.com.br/leilao-de-imoveis/v/caixa-economica-federal",
"logoUrl": "https://static.portalzuk.com.br/comitentes/caixa.png",
"slug": "caixa-economica-federal"
},
"paymentOptions": [
{
"label": "À vista ou em até 12x conforme edital",
"maxInstallments": 12
}
],
"installmentProposal": "Propostas parceladas devem observar a entrada e os prazos indicados no edital.",
"documents": [
{
"id": 12345,
"label": "Edital do leilão",
"url": "https://www.portalzuk.com.br/documento/edital/12345",
"requiresLogin": false
}
]
}| Path | Tipo | Descrição | Exemplo |
|---|---|---|---|
| address.city | string | Cidade do imóvel. | Ribeirão Preto |
| address.formatted | string | Endereço completo apresentado. | Rua Regina Aurea Barroso Reis, 96 - Residencial Greenville - Ribeirão Preto/SP |
| address.latitude | number | Latitude publicada na página. | -21.1767 |
| address.longitude | number | Longitude publicada na página. | -47.8208 |
| address.state | string | UF do imóvel. | SP |
| auctionId | integer | Identificador do leilão. | 36784 |
| auctionRelationUrl | string (URL) | Link para a listagem da modalidade. | https://www.portalzuk.com.br/leilao-de-imoveis/tl/residenciais/leilao-judicial |
| auctionRounds[].date | string (ISO datetime) | Data normalizada da rodada. | 2026-07-22T14:00:00.000Z |
| auctionRounds[].discountPercent | number | Desconto indicado para a rodada. | 25 |
| auctionRounds[].label | string | Nome da rodada. | 1º Leilão |
| auctionRounds[].price | number | Valor mínimo da rodada. | 450000 |
| auctionType | string | Modalidade de leilão normalizada. | judicial |
| canonicalUrl | string (URL) | URL canônica declarada pela página. | https://www.portalzuk.com.br/imovel/sp/ribeirao-preto/residencial-greenville/rua-regina-aurea-barroso-reis-96/36784-229343 |
| closingLabel | string | Texto de encerramento exibido. | Encerramento do leilão |
| commissionPercent | number | Percentual de comissão. | 5 |
| currentBid | number | Maior lance/valor atual quando publicado. | 450000 |
| description | string | Descrição do imóvel. | Casa residencial com área construída, terreno e dependências descritas no edital. |
| discountPercent | number | Desconto em relação à avaliação. | 25 |
| documents[].label | string | Nome do documento. | Edital do leilão |
| documents[].requiresLogin | boolean | Indica se o acesso exige autenticação na fonte. | false |
| documents[].url | string (URL) | URL pública do documento quando disponível. | https://www.portalzuk.com.br/documento/edital/12345 |
| extractedAt | string (ISO datetime) | Instante da extração. | 2026-07-15T12:00:05.000Z |
| features[].label | string | Nome da característica. | Área construída |
| features[].value | string | Valor textual da característica. | 180,00 m² |
| images[] | string (URL) | Galeria de imagens. | https://static.portalzuk.com.br/imovel/detalhe/229343-1.jpg |
| installmentProposal | string | Condições para proposta parcelada. | Propostas parceladas devem observar a entrada e os prazos indicados no edital. |
| lawsuitNumber | string | Número do processo judicial. | 1001234-56.2025.8.26.0000 |
| lawsuitUrl | string (URL) | Link relacionado ao processo. | https://www.portalzuk.com.br/documento/processo/229343 |
| lotId | integer | Identificador do lote/imóvel. | 229343 |
| lotNumber | string | Número do lote no leilão. | 1 |
| minimumBid | number | Menor valor identificado nas rodadas. | 450000 |
| minimumIncrement | number | Incremento mínimo de lance. | 5000 |
| observations | string | Observações e ressalvas do lote. | Consulte o edital e os documentos antes de participar. |
| occupancyStatus | string | Texto de ocupação exibido. | Imóvel desocupado |
| occupied | boolean | Indicador normalizado de ocupação. | false |
| parser | "1.0.0" | Versão estável do formato de resposta da API. | 1.0.0 |
| participationUrl | string (URL) | Link público para participação. | https://www.portalzuk.com.br/participar/36784/229343 |
| paymentOptions[].label | string | Descrição da forma de pagamento. | À vista ou em até 12x conforme edital |
| paymentOptions[].maxInstallments | integer | Máximo de parcelas identificado. | 12 |
| propertyType | string | Tipo do imóvel. | Casa |
| registration | string | Texto de matrícula/registro. | Matrícula 123456 do 1º Cartório de Registro de Imóveis. Nº Contribuinte: 1234567 |
| requestUrl | string (URL) | Mesmo valor de `url`; nunca expõe o endpoint interno consultado. | https://www.portalzuk.com.br/imovel/sp/ribeirao-preto/residencial-greenville/rua-regina-aurea-barroso-reis-96/36784-229343 |
| seller.name | string | Nome do vendedor/comitente. | Caixa Econômica Federal |
| seller.slug | string | Slug do vendedor para novas buscas. | caixa-economica-federal |
| source | "portalzuk.com.br" | Fonte normalizada da extração. | portalzuk.com.br |
| taxpayerId | string | Número de contribuinte quando identificado. | 1234567 |
| title | string | Título do imóvel. | Casa à venda em leilão |
| type | "pdp" | Tipo PDP da seam. | pdp |
| visitation | string | Regras e informações de visitação. | Visitação mediante agendamento conforme as regras do leilão. |
| zukCode | string | Código interno exibido pelo Portal Zuk. | ZUK229343 |
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. |