// docs

Netshoes PLP

Extrai listagem de produtos (PLP) da Netshoes com URL pronta opcional ou busca por keyword, incluindo ordenacao, paginacao, tamanhos e seller do impression layer.

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://www.netshoes.com.br/busca/tenis-adidas?sort=lowest-first",
  "target": "netshoes.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

netshoes_com_br_plp

Auth

Bearer ou X-API-Key

netshoes_com_br_plp tools/call

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "netshoes_com_br_plp",
    "arguments": {
      "url": "https://www.netshoes.com.br/busca/tenis-adidas?sort=lowest-first",
      "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	Opcional. Quando enviada, deve apontar para uma busca/listagem da Netshoes; 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 backend monta a URL /busca/... automaticamente a partir dela.	-	iphone 15 pro max
sort Ordenacao para OLX PLP, Booking Review e Hoteis Review. 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" \| "price_relevance" \| "most_relevant" \| "newest_first" \| "oldest_first" \| "score_desc" \| "score_asc"	Opcional	Ordenacao suportada: relevance, date, price, biggest_price ou score_desc.	relevance	date
target Fonte alvo da extração.	enum	Obrigatório	Sempre obrigatorio no payload e deve ser netshoes.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
page Paginacao. Em PLP inicia em 1; em review (MercadoLivre, Booking e Hoteis) inicia em 0.	integer	Opcional	Paginacao 1-based. O backend aplica o parametro page na URL publica da Netshoes.	1	2

Exemplos de request

PLP por URL

Usa uma URL publica de busca/listagem da Netshoes e pagina explicitamente.

PLP por URL

{
  "url": "https://www.netshoes.com.br/busca/tenis-adidas?sort=lowest-first",
  "target": "netshoes.com.br",
  "type": "plp",
  "page": 2
}

PLP por keyword

Monta automaticamente a URL /busca/... a partir da keyword.

PLP por keyword

{
  "keyword": "tenis adidas",
  "target": "netshoes.com.br",
  "type": "plp",
  "page": 1
}

PLP por keyword com ordenacao

Busca por keyword aplicando ordenacao suportada pelo gateway.

PLP por keyword com ordenacao

{
  "keyword": "tenis adidas",
  "target": "netshoes.com.br",
  "type": "plp",
  "sort": "price",
  "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)",
  "notFound": "boolean (optional; true when the upstream entity was not found and data is null)",
  "data.source": "\"netshoes.com.br\"",
  "data.type": "\"plp\"",
  "data.url": "string",
  "data.requestUrl": "string",
  "data.extractedAt": "string (ISO 8601)",
  "data.query": "string",
  "data.totalResults": "number",
  "data.page": "number",
  "data.totalPages": "number",
  "data.resultsPerPage": "number",
  "data.offset": "number",
  "data.nextPage": "number",
  "data.nextPageUrl": "string",
  "data.items[].url": "string",
  "data.items[].sku": "string",
  "data.items[].productCode": "string",
  "data.items[].name": "string",
  "data.items[].currency": "\"BRL\"",
  "data.items[].price": "number",
  "data.items[].regularPrice": "number",
  "data.items[].discountAmount": "number",
  "data.items[].discountPercent": "number",
  "data.items[].installmentCount": "number",
  "data.items[].sellerName": "string",
  "data.items[].sellerId": "string",
  "data.items[].brand": "string",
  "data.items[].department": "string",
  "data.items[].productType": "string",
  "data.items[].sizes[]": "string",
  "data.items[].available": "boolean",
  "data.items[].aggregateRating.rating": "number",
  "data.items[].aggregateRating.reviewCount": "number",
  "data.items[].thumbnail": "string",
  "data.items[].familyParentCodes[]": "string",
  "data.items[].stamps[]": "string"
}

Exemplo de response

responseExample

{
  "requestId": "req_netshoes_plp_demo",
  "executionId": "exec_netshoes_plp_demo",
  "data": {
    "source": "netshoes.com.br",
    "type": "plp",
    "url": "https://www.netshoes.com.br/busca/tenis-adidas?page=2&sort=lowest-first",
    "requestUrl": "https://www.netshoes.com.br/busca/tenis-adidas?page=2&sort=lowest-first",
    "extractedAt": "2026-04-17T12:00:00.000Z",
    "query": "tenis adidas",
    "totalResults": 2370,
    "page": 2,
    "totalPages": 24,
    "resultsPerPage": 100,
    "offset": 100,
    "nextPage": 3,
    "nextPageUrl": "https://www.netshoes.com.br/busca/tenis-adidas?page=3&sort=lowest-first",
    "items": [
      {
        "url": "https://www.netshoes.com.br/p/tenis-adidas-breaknet-FB9-9335-205",
        "sku": "FB9-9335-205",
        "productCode": "FB9-9335",
        "name": "Tênis Adidas Breaknet",
        "currency": "BRL",
        "currencyRaw": "R$",
        "price": 229.99,
        "regularPrice": 349.99,
        "discountAmount": 120,
        "discountPercent": 34,
        "installmentCount": 5,
        "sellerName": "L_NETSHOES",
        "sellerId": "L_NETSHOES",
        "brand": "Adidas",
        "department": "Casual",
        "productType": "Tênis",
        "sizes": [
          "39",
          "40",
          "41"
        ],
        "available": true,
        "aggregateRating": {
          "rating": 4.71,
          "reviewCount": 9552
        },
        "thumbnail": "https://static.netshoes.com.br/produtos/tenis-adidas-breaknet/05/FB9-9335-205/FB9-9335-205_zoom1.jpg",
        "familyParentCodes": [
          "FB9-9335-006"
        ],
        "stamps": [
          "NetsGO"
        ]
      }
    ]
  }
}

Referência completa de campos

Path	Tipo	Descrição	Exemplo
data.extractedAt	string (ISO 8601)	Timestamp ISO 8601 da extracao.	2026-04-17T12:00:00.000Z
data.items[].aggregateRating.rating	number	Nota media agregada do item.	4.71
data.items[].aggregateRating.reviewCount	number	Quantidade de reviews do item.	9552
data.items[].available	boolean	Indica se o card informa disponibilidade.	true
data.items[].brand	string	Marca do produto listado.	Adidas
data.items[].currency	"BRL"	Moeda padrao da listagem.	BRL
data.items[].department	string	Departamento do produto listado.	Casual
data.items[].discountAmount	number	Desconto absoluto calculado/em centavos convertidos para reais.	120
data.items[].discountPercent	number	Percentual de desconto do item.	34
data.items[].familyParentCodes[]	string	Outros parent codes relacionados ao item.	FB9-9335-006
data.items[].installmentCount	number	Numero de parcelas exibido no card.	5
data.items[].name	string	Nome do produto listado.	Tênis Adidas Breaknet
data.items[].price	number	Preco de venda do item.	229.99
data.items[].productCode	string	Codigo pai/familia do produto listado.	FB9-9335
data.items[].productType	string	Tipo de produto listado.	Tênis
data.items[].regularPrice	number	Preco de lista do item.	349.99
data.items[].sellerId	string	Identificador bruto do seller quando disponivel.	L_NETSHOES
data.items[].sellerName	string	Seller identificado no impression layer da Netshoes.	L_NETSHOES
data.items[].sizes[]	string	Tamanhos mostrados no card/listagem.	39
data.items[].sku	string	SKU ou codigo da variante principal exibida no card.	FB9-9335-205
data.items[].stamps[]	string	Selos/badges comerciais publicados no card.	NetsGO
data.items[].thumbnail	string	Imagem principal/thumbnail do card.	https://static.netshoes.com.br/produtos/tenis-adidas-breaknet/05/FB9-9335-205/FB9-9335-205_zoom1.jpg
data.items[].url	string	URL absoluta do produto listado.	https://www.netshoes.com.br/p/tenis-adidas-breaknet-FB9-9335-205
data.nextPage	number	Numero da proxima pagina quando disponivel.	3
data.nextPageUrl	string	URL publica pronta para requisitar a proxima pagina.	https://www.netshoes.com.br/busca/tenis-adidas?page=3&sort=lowest-first
data.offset	number	Deslocamento numerico derivado de pagina e pageSize.	100
data.page	number	Pagina atual 1-based.	2
data.query	string	Consulta textual associada a listagem.	tenis adidas
data.requestUrl	string	URL efetivamente requisitada ao upstream via Zyte.	https://www.netshoes.com.br/busca/tenis-adidas?page=2&sort=lowest-first
data.resultsPerPage	number	Quantidade de itens por pagina reportada no payload.	100
data.source	"netshoes.com.br"	Fonte logica do scraper.	netshoes.com.br
data.totalPages	number	Quantidade total de paginas disponiveis.	24
data.totalResults	number	Quantidade total de resultados informada pela Netshoes.	2370
data.type	"plp"	Tipo logico do scraper.	plp
data.url	string	URL publica usada como referencia da busca.	https://www.netshoes.com.br/busca/tenis-adidas?page=2&sort=lowest-first
executionId	string (uuid)	Identificador unico da execucao do worker.	exec_netshoes_plp_demo
notFound	boolean (optional; true when the upstream entity was not found and data is null)	Indicador opcional para respostas onde a entidade nao existe no upstream.	N/A
requestId	string (uuid)	Identificador unico da requisicao atendida pelo gateway.	req_netshoes_plp_demo

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.