// docs

Shopee PLP

Extrai resultados de busca/listagem (PLP) da Shopee Brasil usando Zyte renderizado com screenshot e network capture para interceptar o search_items. Custo: 25 creditos por request.

Tempo de resposta: Em algumas execuções, esta API pode levar até 1 minuto para responder. Isso é normal para este endpoint. Aguarde a conclusão da requisição e tenha paciência.

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 '{
  "keyword": "notebook gamer",
  "target": "shopee.com.br",
  "type": "plp"
}'

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

shopee_com_br_plp

Auth

Bearer ou X-API-Key

shopee_com_br_plp tools/call

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "shopee_com_br_plp",
    "arguments": {
      "keyword": "notebook gamer",
      "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	Opcional. Quando enviada, deve ser uma URL publica de busca da Shopee em /search com query param keyword; quando ausente, keyword passa a ser obrigatoria.	-	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	Obrigatoria quando url nao for enviada. O gateway monta a URL /search automaticamente a partir dela.	-	iphone 15 pro max
target Fonte alvo da extração.	enum	Obrigatório	Sempre obrigatorio no payload e deve ser shopee.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.	-	pdp

Exemplos de request

PLP por keyword

Monta automaticamente a URL publica /search da Shopee a partir da keyword.

PLP por keyword

{
  "keyword": "notebook gamer",
  "target": "shopee.com.br",
  "type": "plp"
}

PLP por URL de busca

Usa uma URL publica de busca da Shopee quando voce ja tem a pesquisa pronta.

PLP por URL de busca

{
  "url": "https://shopee.com.br/search?keyword=notebook%20gamer",
  "target": "shopee.com.br",
  "type": "plp"
}

Schema de response (leaf paths)

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

responseSchema

{
  "requestId": "string (uuid)",
  "executionId": "string (uuid)",
  "notFound": "boolean (optional; true when the upstream entity was not found and data is null)",
  "data.source": "string",
  "data.type": "string",
  "data.url": "string",
  "data.requestUrl": "string",
  "data.extractedAt": "string (iso datetime)",
  "data.query": "string",
  "data.totalResults": "number",
  "data.primaryResults": "number",
  "data.page": "number",
  "data.resultsPerPage": "number",
  "data.offset": "number",
  "data.nextPage": "number | null",
  "data.nextPageUrl": "string | null (optional)",
  "data.items[].url": "string",
  "data.items[].itemId": "string",
  "data.items[].shopId": "string",
  "data.items[].sku": "string",
  "data.items[].name": "string",
  "data.items[].currency": "string",
  "data.items[].currencyRaw": "string",
  "data.items[].price": "number",
  "data.items[].priceMin": "number",
  "data.items[].priceMax": "number",
  "data.items[].regularPrice": "number",
  "data.items[].regularPriceMin": "number",
  "data.items[].regularPriceMax": "number",
  "data.items[].discountPercentage": "number",
  "data.items[].soldCount": "number",
  "data.items[].likedCount": "number",
  "data.items[].stock": "number | null",
  "data.items[].brand": "string",
  "data.items[].categoryId": "string",
  "data.items[].itemStatus": "string",
  "data.items[].thumbnail": "string",
  "data.items[].images[].url": "string",
  "data.items[].variants[]": "string",
  "data.items[].shopLocation": "string",
  "data.items[].sellerName": "string",
  "data.items[].sellerId": "string",
  "data.items[].sellerIsOfficialShop": "boolean | null",
  "data.items[].sellerIsShopeeVerified": "boolean | null",
  "data.items[].sellerIsPreferredPlus": "boolean | null",
  "data.items[].freeShipping": "boolean | null",
  "data.items[].isServiceByShopee": "boolean | null",
  "data.items[].canUseCod": "boolean | null",
  "data.items[].sponsored": "boolean | null",
  "data.items[].aggregateRating.rating": "number | null",
  "data.items[].aggregateRating.reviewCount": "number | null"
}

Exemplo de response

responseExample

{
  "requestId": "f38d98f0-8d1b-42a7-9a15-8f75d20ac1e7",
  "executionId": "5afac754-6361-4f84-8a78-80b8dc6ce6dd",
  "data": {
    "source": "shopee.com.br",
    "type": "plp",
    "url": "https://shopee.com.br/search?keyword=notebook%20gamer",
    "requestUrl": "https://shopee.com.br/api/v4/search/search_items?by=relevancy&keyword=notebook%20gamer&limit=60&newest=0&order=desc&page_type=search&scenario=PAGE_GLOBAL_SEARCH&source=SRP&version=2",
    "extractedAt": "2026-04-18T15:20:30.000Z",
    "query": "notebook gamer",
    "totalResults": 6167,
    "primaryResults": 1,
    "page": 1,
    "resultsPerPage": 60,
    "offset": 0,
    "nextPage": 2,
    "items": [
      {
        "url": "https://shopee.com.br/product/387363734/58254322220",
        "itemId": "58254322220",
        "shopId": "387363734",
        "sku": "58254322220",
        "name": "Notebook Dell 3410 Core I5 10g 8gb 240ssd Detalhe Na Carcaça Cinza (Usado)",
        "currency": "BRL",
        "currencyRaw": "R$",
        "price": 1784.15,
        "priceMin": 1784.15,
        "priceMax": 1784.15,
        "regularPrice": 2099,
        "regularPriceMin": 2099,
        "regularPriceMax": 2099,
        "discountPercentage": 15,
        "soldCount": 254,
        "likedCount": 31,
        "stock": 12,
        "brand": "Dell",
        "categoryId": "100644",
        "itemStatus": "normal",
        "thumbnail": "https://down-br.img.susercontent.com/file/br-11134207-81ztc-mk2ad5a2hypuab",
        "images": [
          {
            "url": "https://down-br.img.susercontent.com/file/br-11134207-81ztc-mk2ad5a2hypuab"
          },
          {
            "url": "https://down-br.img.susercontent.com/file/br-11134207-81ztc-mk2eg23w6sxud7"
          }
        ],
        "variants": [
          "8GB",
          "16GB"
        ],
        "shopLocation": "São Paulo",
        "sellerName": "Loja Dell Usados",
        "sellerId": "387363734",
        "sellerIsOfficialShop": false,
        "sellerIsShopeeVerified": false,
        "sellerIsPreferredPlus": true,
        "freeShipping": true,
        "isServiceByShopee": false,
        "canUseCod": false,
        "sponsored": false,
        "aggregateRating": {
          "rating": 5,
          "reviewCount": 7
        }
      }
    ]
  }
}

Referência completa de campos

Path	Tipo	Descrição	Exemplo
data.extractedAt	string (iso datetime)	Timestamp ISO da extracao.	2026-04-18T15:20:30.000Z
data.items[].aggregateRating.rating	number \| null	Nota agregada do produto.	5
data.items[].aggregateRating.reviewCount	number \| null	Quantidade de reviews/comentarios agregados do card.	7
data.items[].brand	string	Marca do produto.	Dell
data.items[].canUseCod	boolean \| null	Indica se o card sinaliza cash on delivery.	false
data.items[].categoryId	string	Categoria numerica bruta do item.	100644
data.items[].currency	string	Codigo da moeda do item.	BRL
data.items[].currencyRaw	string	Simbolo de moeda exibido pela seam.	R$
data.items[].discountPercentage	number	Percentual de desconto reportado no card.	15
data.items[].freeShipping	boolean \| null	Indica se o card sinaliza frete gratis.	true
data.items[].images[].url	string	Galeria de imagens conhecida no resultado.	https://down-br.img.susercontent.com/file/br-11134207-81ztc-mk2ad5a2hypuab
data.items[].isServiceByShopee	boolean \| null	Indica se o item usa servico da Shopee quando o card expuser essa flag.	false
data.items[].itemId	string	Identificador numerico do item na Shopee.	58254322220
data.items[].itemStatus	string	Status bruto do item na Shopee.	normal
data.items[].likedCount	number	Quantidade de likes/favoritos do item.	31
data.items[].name	string	Titulo do produto exibido na listagem.	Notebook Dell 3410 Core I5 10g 8gb 240ssd Detalhe Na Carcaça Cinza (Usado)
data.items[].price	number	Preco principal retornado pela listagem.	1784.15
data.items[].priceMax	number	Preco maximo do card quando ha faixa de variacoes.	1784.15
data.items[].priceMin	number	Preco minimo do card quando ha faixa de variacoes.	1784.15
data.items[].regularPrice	number	Preco original principal quando presente.	2099
data.items[].regularPriceMax	number	Preco original maximo quando presente.	2099
data.items[].regularPriceMin	number	Preco original minimo quando presente.	2099
data.items[].sellerId	string	Identificador da loja, espelhando shopId.	387363734
data.items[].sellerIsOfficialShop	boolean \| null	Indica se a loja e uma official shop.	false
data.items[].sellerIsPreferredPlus	boolean \| null	Indica se a loja aparece como Preferred Plus.	true
data.items[].sellerIsShopeeVerified	boolean \| null	Indica se a loja aparece como verificada pela Shopee.	false
data.items[].sellerName	string	Nome da loja exibido na listagem.	Loja Dell Usados
data.items[].shopId	string	Identificador numerico da loja na Shopee.	387363734
data.items[].shopLocation	string	Localizacao da loja exibida no card.	São Paulo
data.items[].sku	string	SKU principal do card, espelhando o itemId.	58254322220
data.items[].soldCount	number	Volume de vendas historicas quando exposto no resultado.	254
data.items[].sponsored	boolean \| null	Sinaliza patrocinio quando a resposta expuser um adsid.	false
data.items[].stock	number \| null	Estoque bruto quando o card expuser esse valor.	12
data.items[].thumbnail	string	Imagem principal do card.	https://down-br.img.susercontent.com/file/br-11134207-81ztc-mk2ad5a2hypuab
data.items[].url	string	URL canonica do produto em formato /product/shopId/itemId.	https://shopee.com.br/product/387363734/58254322220
data.items[].variants[]	string	Opcoes de variacao resumidas a partir de tier_variations.	8GB
data.nextPage	number \| null	Proxima pagina logica quando o upstream indica que ainda ha mais resultados.	2
data.nextPageUrl	string \| null (optional)	Campo opcional/nullable. Neste seam normalmente nao ha URL publica de continuacao porque pagina nao e exposta como parametro publico.	N/A
data.offset	number	Offset newest interceptado na chamada da Shopee.	0
data.page	number	Pagina logica derivada do offset newest interceptado.	1
data.primaryResults	number	Quantidade de itens extraidos da resposta atual.	1
data.query	string	Keyword resolvida para a busca.	notebook gamer
data.requestUrl	string	URL efetivamente interceptada via network capture no search_items da Shopee.	https://shopee.com.br/api/v4/search/search_items?by=relevancy&keyword=notebook%20gamer&limit=60&newest=0&order=desc&page_type=search&scenario=PAGE_GLOBAL_SEARCH&source=SRP&version=2
data.resultsPerPage	number	Quantidade de itens por chamada search_items (limit).	60
data.source	string	Target canonico da seam retornada.	shopee.com.br
data.totalResults	number	Quantidade total de resultados reportada pela chamada search_items.	6167
data.type	string	Tipo de extracao executada (plp).	plp
data.url	string	URL publica de busca recebida no payload ou montada automaticamente a partir da keyword.	https://shopee.com.br/search?keyword=notebook%20gamer
executionId	string (uuid)	ID interno da execucao usado para observabilidade e dedupe.	5afac754-6361-4f84-8a78-80b8dc6ce6dd
notFound	boolean (optional; true when the upstream entity was not found and data is null)	Present and true when the upstream entity was not found. In this case data is null and the request still completes successfully.	N/A
requestId	string (uuid)	ID unico da requisicao na camada HTTP.	f38d98f0-8d1b-42a7-9a15-8f75d20ac1e7

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.