// docs

Casas Bahia PLP

Extrai listagem de produtos (PLP) da Casas Bahia via endpoint mobile publico, com paginacao e URL sintetica opcional a partir da keyword.

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 '{
  "url": "https://m.casasbahia.com.br/resultado-da-busca/?query=iphone+16&page=2",
  "target": "casasbahia.com.br",
  "type": "plp",
  "page": 2
}'

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

casasbahia_com_br_plp

Auth

Bearer ou X-API-Key

casasbahia_com_br_plp tools/call

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "casasbahia_com_br_plp",
    "arguments": {
      "url": "https://m.casasbahia.com.br/resultado-da-busca/?query=iphone+16&page=2",
      "page": 2,
      "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)	Condicional	Obrigatorio somente quando keyword nao for enviada.	-	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	Condicional	Obrigatorio quando url nao for enviada.	-	iphone 15 pro max
target Fonte alvo da extração.	enum	Obrigatório	Sempre obrigatorio no payload e deve ser casasbahia.com.br.	casasbahia.com.br	mercadolivre.com.br
type Tipo da extração: pdp, idp, plp, quote, review ou places.	enum	Obrigatório	Sempre obrigatorio no payload e deve ser plp.	plp	pdp
page Paginacao. Em PLP inicia em 1; em review (MercadoLivre, Booking e Hoteis) inicia em 0.	integer	Opcional	Suportado para PLP; deve ser inteiro >= 1.	1	2

Exemplos de request

PLP por URL

Informa a URL publica da busca e a pagina explicitamente.

PLP por URL

{
  "url": "https://m.casasbahia.com.br/resultado-da-busca/?query=iphone+16&page=2",
  "target": "casasbahia.com.br",
  "type": "plp",
  "page": 2
}

PLP por keyword (sem url)

Gateway monta a URL publica automaticamente a partir da keyword.

PLP por keyword (sem url)

{
  "keyword": "iphone 16",
  "target": "casasbahia.com.br",
  "type": "plp",
  "page": 1
}

Schema de response (leaf paths)

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

responseSchema

{
  "requestId": "string (uuid)",
  "executionId": "string (uuid)",
  "data.source": "string",
  "data.type": "string",
  "data.url": "string",
  "data.requestUrl": "string",
  "data.extractedAt": "string (ISO 8601)",
  "data.query": "string",
  "data.totalResults": "integer",
  "data.totalPages": "integer",
  "data.page": "integer",
  "data.resultsPerPage": "integer",
  "data.offset": "integer",
  "data.nextPage": "integer",
  "data.nextPageUrl": "string",
  "data.items[].url": "string",
  "data.items[].productId": "string",
  "data.items[].sku": "string",
  "data.items[].name": "string",
  "data.items[].available": "boolean",
  "data.items[].sellerId": "string",
  "data.items[].brand": "string",
  "data.items[].thumbnail": "string",
  "data.items[].aggregateRating.rating": "number",
  "data.items[].aggregateRating.reviewCount": "integer",
  "data.items[].sponsored": "boolean"
}

Exemplo de response

responseExample

{
  "requestId": "d68564d2-34bc-47e6-a1a6-796794f8463b",
  "executionId": "f7b0f7f6-3363-4958-9f7e-6c0e0d189874",
  "data": {
    "source": "casasbahia.com.br",
    "type": "plp",
    "url": "https://m.casasbahia.com.br/resultado-da-busca/?query=iphone+16&page=1",
    "requestUrl": "https://mobile-b2c.casasbahia.com.br/busca/v4?termo=iphone+16&habilitaredirect=true&habilitaPatrocinado=true&motorBusca=4&PaginaAtual=1&QuantidadePorPagina=10",
    "extractedAt": "2026-04-18T00:00:00.000Z",
    "query": "iphone 16",
    "totalResults": 25,
    "totalPages": 3,
    "page": 1,
    "resultsPerPage": 10,
    "offset": 0,
    "nextPage": 2,
    "nextPageUrl": "https://m.casasbahia.com.br/resultado-da-busca/?query=iphone+16&page=2",
    "items": [
      {
        "url": "https://www.casasbahia.com.br/apple-iphone-16-128gb-61-48mp-preto/p/55067621",
        "productId": "80872678",
        "sku": "55067621",
        "name": "Apple iPhone 16 128GB 6,1 48MP Preto",
        "available": true,
        "sellerId": "228278",
        "brand": "Apple",
        "thumbnail": "https://imgs.casasbahia.com.br/55067621/1xg.jpg",
        "aggregateRating": {
          "rating": 4.9,
          "reviewCount": 128
        },
        "sponsored": true
      }
    ]
  }
}

Referência completa de campos

Path	Tipo	Descrição	Exemplo
data.extractedAt	string (ISO 8601)	Timestamp ISO em que a extracao foi finalizada.	2026-04-18T00:00:00.000Z
data.items[].aggregateRating.rating	number	Nota agregada do item quando presente.	4.9
data.items[].aggregateRating.reviewCount	integer	Quantidade de avaliacoes agregadas quando disponivel.	128
data.items[].available	boolean	Disponibilidade normalizada do item listado.	true
data.items[].brand	string	Marca normalizada do item listado.	Apple
data.items[].name	string	Titulo do item listado.	Apple iPhone 16 128GB 6,1 48MP Preto
data.items[].productId	string	Identificador interno do produto na origem.	80872678
data.items[].sellerId	string	Identificador normalizado do seller principal do item.	228278
data.items[].sku	string	SKU do item listado.	55067621
data.items[].sponsored	boolean	Indica se o resultado veio marcado como patrocinado.	true
data.items[].thumbnail	string	Thumbnail principal do item listado.	https://imgs.casasbahia.com.br/55067621/1xg.jpg
data.items[].url	string	URL publica sintetizada do produto listado.	https://www.casasbahia.com.br/apple-iphone-16-128gb-61-48mp-preto/p/55067621
data.nextPage	integer	Numero da proxima pagina, quando existir.	2
data.nextPageUrl	string	URL publica sintetizada para a proxima pagina, quando existir.	https://m.casasbahia.com.br/resultado-da-busca/?query=iphone+16&page=2
data.offset	integer	Offset calculado a partir da pagina e do tamanho da pagina.	0
data.page	integer	Pagina efetivamente executada.	1
data.query	string	Keyword final resolvida para a busca.	iphone 16
data.requestUrl	string	URL interna do endpoint mobile chamada pelo worker.	https://mobile-b2c.casasbahia.com.br/busca/v4?termo=iphone+16&habilitaredirect=true&habilitaPatrocinado=true&motorBusca=4&PaginaAtual=1&QuantidadePorPagina=10
data.resultsPerPage	integer	Quantidade de itens por pagina usada pelo seam.	10
data.source	string	Fonte normalizada da extracao.	casasbahia.com.br
data.totalPages	integer	Quantidade total de paginas calculada pelo worker.	3
data.totalResults	integer	Quantidade total de resultados retornada pela origem.	25
data.type	string	Tipo do seam executado.	plp
data.url	string	URL publica final usada como referencia da listagem.	https://m.casasbahia.com.br/resultado-da-busca/?query=iphone+16&page=1
executionId	string (uuid)	Identificador unico da execucao do worker para rastreabilidade.	f7b0f7f6-3363-4958-9f7e-6c0e0d189874
requestId	string (uuid)	Identificador unico do request HTTP na GeckoAPI.	d68564d2-34bc-47e6-a1a6-796794f8463b

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.