// docs

Samsung PLP

Busca produtos Samsung 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. Valores monetários em BRL: price é o preço atual; regularPrice é o preço de referência; cashPrice é a menor oferta publicada em uma parcela, incluindo Pix quando informado. installmentPrice e installmentCount correspondem ao maior parcelamento sem juros no cartão. Preços de ofertas indisponíveis são null. Cupons, troca de aparelho e descontos de clubes não são calculados.

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": "samsung.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

samsung_com_br_plp

Auth

Bearer ou X-API-Key

samsung_com_br_plp tools/call

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "samsung_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 shop.samsung.com/br/termo?_q=termo&map=ft. Obrigatória quando keyword não for enviada. Categorias e filtros de categoria não são suportados. Parâmetros de rastreamento são removidos.	-	https://shop.samsung.com/br/geladeira?_q=geladeira&map=ft
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, sem caracteres de controle ou barra invertida. 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, aceita order=OrderByScoreDESC, OrderByPriceASC, OrderByPriceDESC, OrderByReleaseDateDESC ou OrderByBestDiscountDESC.	relevance	price
target Fonte alvo da extração.	enum	Obrigatório	Use samsung.com.br.	samsung.com.br	samsung.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": "samsung.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": "samsung.com.br",
  "type": "plp",
  "url": "https://shop.samsung.com/br/geladeira?_q=geladeira&map=ft",
  "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": "samsung.com.br",
    "type": "plp",
    "url": "https://shop.samsung.com/br/geladeira?_q=geladeira&map=ft&page=1",
    "requestUrl": "https://shop.samsung.com/br/geladeira?_q=geladeira&map=ft&page=1",
    "extractedAt": "2026-10-01T12:17:13.588Z",
    "query": "geladeira",
    "sort": "relevance",
    "totalResults": 100,
    "totalPages": 9,
    "page": 1,
    "resultsPerPage": 12,
    "offset": 0,
    "nextPage": 2,
    "nextPageUrl": "https://shop.samsung.com/br/geladeira?_q=geladeira&map=ft&page=2",
    "items": [
      {
        "url": "https://shop.samsung.com/br/geladeira-samsung-duplex-rt42-inox-bivolt-415l/p?skuId=16004",
        "productId": "13208",
        "sku": "16004",
        "name": "Geladeira Samsung Duplex RT42 Inox Bivolt 415L",
        "available": true,
        "price": 4525.27,
        "regularPrice": 4525.27,
        "cashPrice": 4299.01,
        "installmentPrice": 251.4,
        "installmentCount": 18,
        "sellerId": "1",
        "sellerName": "SAMSUNG ELETRÔNICA DA AMAZÔNIA LTDA.",
        "currency": "BRL",
        "currencyRaw": "R$",
        "brand": "Samsung",
        "thumbnail": "https://samsungbrshop.vteximg.com.br/arquivos/ids/296134/SA365_SMG_RT42C_Galeria_1000x1000_01_20260721.jpg?v=639220673517100000",
        "aggregateRating": null,
        "sponsored": false
      },
      {
        "url": "https://shop.samsung.com/br/geladeira-samsung-duplex-rt47-inox-bivolt-465l/p?skuId=16005",
        "productId": "13209",
        "sku": "16005",
        "name": "Geladeira Samsung Duplex RT47 Inox Bivolt 465L",
        "available": true,
        "price": 4899,
        "regularPrice": 4899,
        "cashPrice": 4899,
        "installmentPrice": 272.16,
        "installmentCount": 18,
        "sellerId": "1",
        "sellerName": "SAMSUNG ELETRÔNICA DA AMAZÔNIA LTDA.",
        "currency": "BRL",
        "currencyRaw": "R$",
        "brand": "Samsung",
        "thumbnail": "https://samsungbrshop.vteximg.com.br/arquivos/ids/296144/SA365_SMG_RT47C_Galeria_1000x1000_01_20260721.jpg?v=639220673657000000",
        "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-10-01T12:17:13.588Z
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.	Samsung
data.items[].cashPrice	number \| null	Menor valor em uma parcela publicado na oferta; não pressupõe desconto no Pix.	4299.01
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.	18
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.	251.4
data.items[].name	string	Nome publicado pela origem.	Geladeira Samsung Duplex RT42 Inox Bivolt 415L
data.items[].price	number \| null	Preço atual em reais; null quando a oferta está indisponível ou sem preço.	4525.27
data.items[].productId	string	Identificador do produto no catálogo Samsung.	13208
data.items[].regularPrice	number \| null	Preço de referência em reais, quando informado.	4525.27
data.items[].sellerId	string \| null	Identificador do vendedor da oferta.	1
data.items[].sellerName	string \| null	Nome do vendedor da oferta.	SAMSUNG ELETRÔNICA DA AMAZÔNIA LTDA.
data.items[].sku	string	Identificador da variação (SKU); voltagens diferentes podem ter SKUs distintos.	16004
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://samsungbrshop.vteximg.com.br/arquivos/ids/296134/SA365_SMG_RT42C_Galeria_1000x1000_01_20260721.jpg?v=639220673517100000
data.items[].url	string	URL pública; no produto, skuId identifica a variação selecionada.	https://shop.samsung.com/br/geladeira-samsung-duplex-rt42-inox-bivolt-415l/p?skuId=16004
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://shop.samsung.com/br/geladeira?_q=geladeira&map=ft&page=2
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://shop.samsung.com/br/geladeira?_q=geladeira&map=ft&page=1
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.	samsung.com.br
data.totalPages	number	Número de páginas acessíveis, limitado a 208.	9
data.totalResults	number	Total informado pelo catálogo para a busca.	100
data.type	string	Tipo de extração.	plp
data.url	string	URL pública; no produto, skuId identifica a variação selecionada.	https://shop.samsung.com/br/geladeira?_q=geladeira&map=ft&page=1
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.