// docs

Brastemp PLP

Busca produtos Brastemp por palavra-chave ou URL, com preços, disponibilidade e paginação. Cada consulta PLP custa 1 crédito.

Tempo de resposta: A busca consulta o catálogo e pode incluir peças e acessórios relacionados ao termo. O exemplo mostra dois itens de uma página de até 12. Ordenação e estoque podem mudar entre consultas. O catálogo limita a janela de resultados; são acessíveis até 208 páginas.

Nota importante: alguns campos podem retornar null em produção, dependendo da página de origem. Consulte o schema e a descrição de cada campo para tratar valores ausentes; os exemplos mostram uma resposta possível.

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": "brastemp.com.br",
  "type": "plp",
  "keyword": "geladeira",
  "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

brastemp_com_br_plp

Auth

Bearer ou X-API-Key

brastemp_com_br_plp tools/call

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "brastemp_com_br_plp",
    "arguments": {
      "keyword": "geladeira",
      "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)	Condicional	URL de busca /s?q=termo. Também aceita busca legada /termo?_q=termo&map=ft. Obrigatória quando keyword não for enviada. Páginas editoriais /categoria/ e filtros de categoria não são suportados.	-	https://www.brastemp.com.br/s?q=geladeira
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	Obrigatória sem URL; de 1 a 200 caracteres. Se enviada com URL, deve corresponder ao termo da URL.	-	geladeira
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	relevance, price, biggest_price, date ou biggest_discount. Na URL, também aceita score_desc, price_asc, price_desc, release_desc e discount_desc.	relevance	price
target Fonte alvo da extração.	enum	Obrigatório	Use brastemp.com.br.	brastemp.com.br	brastemp.com.br
type Tipo da extração: pdp, idp, plp, ilp, quote, review ou places.	enum	Obrigatório	Use plp.	plp	plp
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	Inteiro de 1 a 208. Até 12 produtos por página; omita para usar a página na URL, ou 1. Use nextPageUrl para continuar.	1	1

Exemplos de request

Busca por palavra-chave

Cada página consultada custa 1 crédito e retorna até 12 produtos.

Busca por palavra-chave

{
  "target": "brastemp.com.br",
  "type": "plp",
  "keyword": "geladeira",
  "page": 1
}

Busca por URL e menor preço

page e sort enviados no payload têm prioridade sobre os valores da URL.

Busca por URL e menor preço

{
  "target": "brastemp.com.br",
  "type": "plp",
  "url": "https://www.brastemp.com.br/s?q=geladeira",
  "page": 2,
  "sort": "price"
}

Schema de response (leaf paths)

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

responseSchema

{
  "requestId": "string",
  "executionId": "string",
  "data.source": "string",
  "data.type": "string",
  "data.url": "string",
  "data.requestUrl": "string",
  "data.extractedAt": "string",
  "data.query": "string",
  "data.sort": "string",
  "data.totalResults": "number",
  "data.totalPages": "number",
  "data.page": "number",
  "data.resultsPerPage": "number",
  "data.offset": "number",
  "data.nextPage": "number | null",
  "data.nextPageUrl": "string | null",
  "data.items[].url": "string",
  "data.items[].productId": "string",
  "data.items[].sku": "string",
  "data.items[].name": "string",
  "data.items[].available": "boolean | null",
  "data.items[].price": "number | null",
  "data.items[].regularPrice": "number | null",
  "data.items[].cashPrice": "number | null",
  "data.items[].installmentPrice": "number | null",
  "data.items[].installmentCount": "number | null",
  "data.items[].sellerId": "string | null",
  "data.items[].sellerName": "string | null",
  "data.items[].currency": "string",
  "data.items[].currencyRaw": "string",
  "data.items[].brand": "string | null",
  "data.items[].thumbnail": "string | null",
  "data.items[].aggregateRating": "null",
  "data.items[].sponsored": "boolean"
}

Exemplo de response

responseExample

{
  "requestId": "d68564d2-34bc-47e6-a1a6-796794f8463b",
  "executionId": "f7b0f7f6-3363-4958-9f7e-6c0e0d189874",
  "data": {
    "source": "brastemp.com.br",
    "type": "plp",
    "url": "https://www.brastemp.com.br/s?q=geladeira&page=1&sort=score_desc",
    "requestUrl": "https://www.brastemp.com.br/s?q=geladeira&page=1&sort=score_desc",
    "extractedAt": "2026-09-30T16:37:14.587Z",
    "query": "geladeira",
    "sort": "relevance",
    "totalResults": 646,
    "totalPages": 54,
    "page": 1,
    "resultsPerPage": 12,
    "offset": 0,
    "nextPage": 2,
    "nextPageUrl": "https://www.brastemp.com.br/s?q=geladeira&page=2&sort=score_desc",
    "items": [
      {
        "url": "https://www.brastemp.com.br/geladeira-inteligente-b-smart-brastemp-frost-free-3-portas-french-door-630-litros-cor-inox-bro88ak/p?skuId=326199396",
        "productId": "20128057",
        "sku": "326199396",
        "name": "Geladeira Inteligente B= Smart 3 Portas French Door Frost Free 630L Inox Brastemp - BRO88AK",
        "available": true,
        "price": 6999,
        "regularPrice": 6999,
        "cashPrice": 6999,
        "installmentPrice": 333.28,
        "installmentCount": 21,
        "sellerId": "1",
        "sellerName": "Brastemp",
        "currency": "BRL",
        "currencyRaw": "R$",
        "brand": "Brastemp",
        "thumbnail": "https://brastemp.vteximg.com.br/arquivos/ids/297182/01_Brastemp_Geladeira_BRO88AK.jpg?v=639246598006000000",
        "aggregateRating": null,
        "sponsored": false
      },
      {
        "url": "https://www.brastemp.com.br/geladeira-inteligente-b-smart-3-portas-french-door-frost-free-630l-branca-brastemp-bro88ab/p?skuId=326199397",
        "productId": "20128058",
        "sku": "326199397",
        "name": "Geladeira Inteligente B= Smart 3 Portas French Door Frost Free 630L Branca Brastemp - BRO88AB",
        "available": true,
        "price": 6425,
        "regularPrice": 6425,
        "cashPrice": 6425,
        "installmentPrice": 305.95,
        "installmentCount": 21,
        "sellerId": "1",
        "sellerName": "Brastemp",
        "currency": "BRL",
        "currencyRaw": "R$",
        "brand": "Brastemp",
        "thumbnail": "https://brastemp.vteximg.com.br/arquivos/ids/297140/01_Brastemp_Geladeira_BRO88AB.jpg?v=639246596029700000",
        "aggregateRating": null,
        "sponsored": false
      }
    ]
  }
}

Referência completa de campos

Path	Tipo	Descrição	Exemplo
data.extractedAt	string	Data e hora da extração em ISO 8601.	2026-09-30T16:37:14.587Z
data.items[].aggregateRating	null	Avaliação agregada; null porque o catálogo consultado não fornece avaliações.	null
data.items[].available	boolean \| null	Disponibilidade do SKU selecionado; null quando a origem não informa.	true
data.items[].brand	string \| null	Marca do produto.	Brastemp
data.items[].cashPrice	number \| null	Menor valor em uma parcela publicado na oferta; não pressupõe desconto no Pix.	6999
data.items[].currency	string	Moeda da oferta: BRL.	BRL
data.items[].currencyRaw	string	Símbolo da moeda: R$.	R$
data.items[].installmentCount	number \| null	Quantidade de parcelas sem juros em cartão de crédito dessa opção.	21
data.items[].installmentPrice	number \| null	Valor da parcela da opção com mais parcelas sem juros em cartão de crédito, quando disponível.	333.28
data.items[].name	string	Nome publicado pela origem.	Geladeira Inteligente B= Smart 3 Portas French Door Frost Free 630L Inox Brastemp - BRO88AK
data.items[].price	number \| null	Preço atual em reais; null quando a oferta está indisponível ou sem preço.	6999
data.items[].productId	string	Identificador do produto no catálogo Brastemp.	20128057
data.items[].regularPrice	number \| null	Preço de referência em reais, quando informado.	6999
data.items[].sellerId	string \| null	Identificador do vendedor da oferta.	1
data.items[].sellerName	string \| null	Nome do vendedor da oferta.	Brastemp
data.items[].sku	string	Identificador da variação (SKU); voltagens diferentes podem ter SKUs distintos.	326199396
data.items[].sponsored	boolean	false: a busca do catálogo não marca estes resultados como patrocinados.	false
data.items[].thumbnail	string \| null	URL da imagem principal do SKU.	https://brastemp.vteximg.com.br/arquivos/ids/297182/01_Brastemp_Geladeira_BRO88AK.jpg?v=639246598006000000
data.items[].url	string	URL pública; no produto, skuId identifica a variação selecionada.	https://www.brastemp.com.br/geladeira-inteligente-b-smart-brastemp-frost-free-3-portas-french-door-630-litros-cor-inox-bro88ak/p?skuId=326199396
data.nextPage	number \| null	Próxima página, ou null no final da paginação.	2
data.nextPageUrl	string \| null	URL pública da próxima página, preservando busca e ordenação; null no final.	https://www.brastemp.com.br/s?q=geladeira&page=2&sort=score_desc
data.offset	number	Posição inicial da página no catálogo.	0
data.page	number	Página consultada, começando em 1.	1
data.query	string	Palavra-chave da busca.	geladeira
data.requestUrl	string	URL pública normalizada da busca, igual a url.	https://www.brastemp.com.br/s?q=geladeira&page=1&sort=score_desc
data.resultsPerPage	number	Tamanho da página: até 12 produtos.	12
data.sort	string	Ordenação normalizada: relevance, price, biggest_price, date ou biggest_discount.	relevance
data.source	string	Domínio da origem.	brastemp.com.br
data.totalPages	number	Número de páginas acessíveis, limitado a 208.	54
data.totalResults	number	Total informado pelo catálogo para a busca.	646
data.type	string	Tipo de extração.	plp
data.url	string	URL pública; no produto, skuId identifica a variação selecionada.	https://www.brastemp.com.br/s?q=geladeira&page=1&sort=score_desc
executionId	string	Identificador da execução do worker.	f7b0f7f6-3363-4958-9f7e-6c0e0d189874
requestId	string	Identificador da requisição 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.