// docs

Shopee PDP

Extrai dados ricos de produto (PDP) da Shopee Brasil a partir do HTML bruto da pagina, incluindo seller, variacoes, midia, frete, estoque e atributos.

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 '{
  "url": "https://shopee.com.br/Rel%C3%B3gio-Technos-Quadrado-Executive-2115TVM0A-Pulseira-Couro-Legitimo-i.1157985386.23897901346",
  "target": "shopee.com.br",
  "type": "pdp"
}'

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_pdp

Auth

Bearer ou X-API-Key

shopee_com_br_pdp tools/call

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "shopee_com_br_pdp",
    "arguments": {
      "url": "https://shopee.com.br/Rel%C3%B3gio-Technos-Quadrado-Executive-2115TVM0A-Pulseira-Couro-Legitimo-i.1157985386.23897901346",
      "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)	Obrigatório	Obrigatorio para este seam.	-	https://www.mercadolivre.com.br/p/MLB123456
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 pdp.	-	pdp

Exemplos de request

PDP por URL

Requisicao basica para pagina de produto Shopee.

PDP por URL

{
  "url": "https://shopee.com.br/Rel%C3%B3gio-Technos-Quadrado-Executive-2115TVM0A-Pulseira-Couro-Legitimo-i.1157985386.23897901346",
  "target": "shopee.com.br",
  "type": "pdp"
}

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.canonicalUrl": "string",
  "data.url": "string",
  "data.name": "string",
  "data.itemId": "string",
  "data.shopId": "string",
  "data.sku": "string",
  "data.sellerId": "string",
  "data.sellerUserId": "string",
  "data.sellerName": "string",
  "data.sellerUsername": "string",
  "data.sellerUrl": "string",
  "data.sellerLocation": "string",
  "data.sellerProducts": "number",
  "data.sellerFollowers": "number",
  "data.sellerRating": "number",
  "data.sellerResponseRate": "number",
  "data.sellerResponseTimeSeconds": "number",
  "data.sellerIsOfficialShop": "boolean",
  "data.sellerIsShopeeVerified": "boolean",
  "data.sellerIsPreferredPlus": "boolean",
  "data.brand.name": "string",
  "data.currency": "string",
  "data.price": "number (optional; when present in Shopee's embedded PDP state)",
  "data.regularPrice": "number (optional; when present in Shopee's embedded PDP state)",
  "data.priceHint": "string (optional)",
  "data.pixDiscount": "number (optional)",
  "data.freeShipping": "boolean",
  "data.shippingFromLocation": "string",
  "data.shippingChannels[].name": "string",
  "data.shippingChannels[].shippingFee": "number",
  "data.shippingChannels[].shippingFeeBeforeDiscount": "number (optional)",
  "data.shippingChannels[].estimatedDeliveryText": "string (optional)",
  "data.shippingChannels[].estimatedDeliveryTimeMinDays": "number (optional)",
  "data.shippingChannels[].estimatedDeliveryTimeMaxDays": "number (optional)",
  "data.availability": "string",
  "data.itemStatus": "string",
  "data.itemCondition": "string",
  "data.stock": "number",
  "data.likedCount": "number",
  "data.aggregateRating.ratingValue": "number",
  "data.aggregateRating.reviewCount": "number",
  "data.aggregateRating.bestRating": "number",
  "data.breadcrumbs[].name": "string",
  "data.breadcrumbs[].url": "string",
  "data.additionalProperties[].name": "string",
  "data.additionalProperties[].value": "string",
  "data.tierVariations[].name": "string",
  "data.tierVariations[].options[]": "string",
  "data.variants[]": "string",
  "data.description": "string",
  "data.mainImage.url": "string",
  "data.images[].url": "string",
  "data.videos[].url": "string",
  "data.videos[].thumbnailUrl": "string",
  "data.videos[].durationSeconds": "number"
}

Exemplo de response

responseExample

{
  "requestId": "66666666-1111-4111-8111-666666666666",
  "executionId": "66666666-2222-4222-8222-666666666666",
  "data": {
    "canonicalUrl": "https://shopee.com.br/Rel%C3%B3gio-Technos-Quadrado-Executive-2115TVM0A-Pulseira-Couro-Legitimo-i.1157985386.23897901346",
    "url": "https://shopee.com.br/Rel%C3%B3gio-Technos-Quadrado-Executive-2115TVM0A-Pulseira-Couro-Legitimo-i.1157985386.23897901346",
    "name": "Relogio Technos Quadrado Executive 2115TVM0A Pulseira Couro Legitimo",
    "itemId": "23897901346",
    "shopId": "1157985386",
    "sku": "23897901346",
    "sellerId": "1157985386",
    "sellerUserId": "1158329411",
    "sellerName": "Zilla Relogios",
    "sellerUsername": "zillaz.relogios",
    "sellerUrl": "https://shopee.com.br/zillaz.relogios",
    "sellerLocation": "Paicandu, Parana",
    "sellerProducts": 69,
    "sellerFollowers": 655,
    "sellerRating": 4.931507,
    "sellerResponseRate": 100,
    "sellerResponseTimeSeconds": 3822,
    "sellerIsOfficialShop": false,
    "sellerIsShopeeVerified": false,
    "sellerIsPreferredPlus": false,
    "brand": {
      "name": "Technos"
    },
    "currency": "BRL",
    "priceHint": "no Pix >",
    "freeShipping": false,
    "shippingFromLocation": "Parana",
    "shippingChannels": [
      {
        "name": "Entrega Padrao",
        "shippingFee": 0,
        "shippingFeeBeforeDiscount": 8.15,
        "estimatedDeliveryText": "Receba entre 18 e 23/abr",
        "estimatedDeliveryTimeMinDays": 2,
        "estimatedDeliveryTimeMaxDays": 7
      }
    ],
    "availability": "InStock",
    "itemStatus": "normal",
    "itemCondition": "new",
    "stock": 10,
    "likedCount": 842,
    "aggregateRating": {
      "ratingValue": 4.96875,
      "reviewCount": 32,
      "bestRating": 5
    },
    "breadcrumbs": [
      {
        "name": "Shopee",
        "url": "https://shopee.com.br/"
      },
      {
        "name": "Relogios",
        "url": "https://shopee.com.br/Rel%C3%B3gios-cat.11059996"
      }
    ],
    "additionalProperties": [
      {
        "name": "Material da Correia",
        "value": "Couro"
      }
    ],
    "tierVariations": [
      {
        "name": "Cor",
        "options": [
          "Preto",
          "Marrom"
        ]
      }
    ],
    "variants": [
      "Preto",
      "Marrom"
    ],
    "description": "Descricao do produto",
    "mainImage": {
      "url": "https://down-br.img.susercontent.com/file/br-11134207-7r98o-m17evk1ooacz76"
    },
    "images": [
      {
        "url": "https://down-br.img.susercontent.com/file/br-11134207-7r98o-m17evk1ooacz76"
      },
      {
        "url": "https://down-br.img.susercontent.com/file/br-11134207-7r98o-m17evk1opoxfe8"
      }
    ],
    "videos": [
      {
        "url": "https://mms.vod.susercontent.com/video.mp4",
        "thumbnailUrl": "https://down-br.img.susercontent.com/file/br-11110105-7r98o-thumbhash",
        "durationSeconds": 38
      }
    ]
  }
}

Referência completa de campos

Path	Tipo	Descrição	Exemplo
data.additionalProperties[].name	string	Nome de um atributo/especificacao do item.	Material da Correia
data.additionalProperties[].value	string	Valor da especificacao correspondente.	Couro
data.aggregateRating.bestRating	number	Nota maxima da escala de avaliacao.	5
data.aggregateRating.ratingValue	number	Nota media agregada do produto.	4.96875
data.aggregateRating.reviewCount	number	Quantidade total de avaliacoes/comentarios agregados.	32
data.availability	string	Disponibilidade normalizada com base nos modelos/estoque.	InStock
data.brand.name	string	Marca do produto.	Technos
data.breadcrumbs[].name	string	Nome do breadcrumb SEO.	Shopee
data.breadcrumbs[].url	string	URL do breadcrumb SEO.	https://shopee.com.br/
data.canonicalUrl	string	URL canonica inferida a partir do BreadcrumbList/SEO da pagina.	https://shopee.com.br/Rel%C3%B3gio-Technos-Quadrado-Executive-2115TVM0A-Pulseira-Couro-Legitimo-i.1157985386.23897901346
data.currency	string	Codigo da moeda capturada no item.	BRL
data.description	string	Descricao textual do produto vinda do estado embedado do item.	Descricao do produto
data.freeShipping	boolean	Indica se o estado de shipping marca frete gratis nativo.	false
data.images[].url	string	Imagens adicionais do produto.	https://down-br.img.susercontent.com/file/br-11134207-7r98o-m17evk1ooacz76
data.itemCondition	string	Condicao do item normalizada a partir do campo condition.	new
data.itemId	string	Identificador numerico do item na Shopee.	23897901346
data.itemStatus	string	Status bruto do item na Shopee.	normal
data.likedCount	number	Quantidade de likes/favoritos exibidos para o item.	842
data.mainImage.url	string	Imagem principal do produto.	https://down-br.img.susercontent.com/file/br-11134207-7r98o-m17evk1ooacz76
data.name	string	Titulo do produto exibido no PDP.	Relogio Technos Quadrado Executive 2115TVM0A Pulseira Couro Legitimo
data.pixDiscount	number (optional)	Valor do desconto Pix quando o embed expor esse dado numerico.	N/A
data.price	number (optional; when present in Shopee's embedded PDP state)	Preco principal do item quando presente no estado embedado do PDP.	N/A
data.priceHint	string (optional)	Hint textual de preco/promocao exibido no bloco de preco (ex: no Pix).	no Pix >
data.regularPrice	number (optional; when present in Shopee's embedded PDP state)	Preco antes de desconto quando presente no estado embedado do PDP.	N/A
data.sellerFollowers	number	Quantidade de seguidores da loja.	655
data.sellerId	string	Identificador numerico da loja/seller.	1157985386
data.sellerIsOfficialShop	boolean	Indica se a loja e marcada como Official Shop.	false
data.sellerIsPreferredPlus	boolean	Indica se a loja participa do programa Preferred Plus.	false
data.sellerIsShopeeVerified	boolean	Indica se a loja e marcada como verificada pela Shopee.	false
data.sellerLocation	string	Localizacao textual da loja/seller.	Paicandu, Parana
data.sellerName	string	Nome publico da loja no PDP.	Zilla Relogios
data.sellerProducts	number	Quantidade de produtos publicados pela loja.	69
data.sellerRating	number	Nota media agregada da loja.	4.931507
data.sellerResponseRate	number	Taxa de resposta do chat da loja em percentual.	100
data.sellerResponseTimeSeconds	number	Tempo medio de resposta do chat em segundos quando informado pelo embed.	3822
data.sellerUrl	string	URL publica da loja.	https://shopee.com.br/zillaz.relogios
data.sellerUserId	string	Identificador numerico do usuario proprietario da loja.	1158329411
data.sellerUsername	string	Username/slug da loja usado na URL publica.	zillaz.relogios
data.shippingChannels[].estimatedDeliveryText	string (optional)	Texto curto de prazo exibido para o canal.	Receba entre 18 e 23/abr
data.shippingChannels[].estimatedDeliveryTimeMaxDays	number (optional)	Maior prazo estimado em dias para o canal.	7
data.shippingChannels[].estimatedDeliveryTimeMinDays	number (optional)	Menor prazo estimado em dias para o canal.	2
data.shippingChannels[].name	string	Nome do canal/logistica de envio.	Entrega Padrao
data.shippingChannels[].shippingFee	number	Frete atual normalizado para decimal.	0
data.shippingChannels[].shippingFeeBeforeDiscount	number (optional)	Frete antes de subsidio/desconto quando exposto.	8.15
data.shippingFromLocation	string	UF/local de origem do envio.	Parana
data.shopId	string	Identificador numerico da loja na Shopee.	1157985386
data.sku	string	Identificador primario do item; hoje replica o itemId quando nao ha SKU separado.	23897901346
data.stock	number	Soma do estoque retornado para os modelos selecionaveis.	10
data.tierVariations[].name	string	Nome de uma dimensao de variacao (ex: Cor, Tamanho).	Cor
data.tierVariations[].options[]	string	Opcoes disponiveis para a variacao.	Preto
data.url	string	URL efetivamente usada para a extracao.	https://shopee.com.br/Rel%C3%B3gio-Technos-Quadrado-Executive-2115TVM0A-Pulseira-Couro-Legitimo-i.1157985386.23897901346
data.variants[]	string	Lista achatada de opcoes de variacao.	Preto
data.videos[].durationSeconds	number	Duracao do video em segundos.	38
data.videos[].thumbnailUrl	string	Thumbnail do video do item.	https://down-br.img.susercontent.com/file/br-11110105-7r98o-thumbhash
data.videos[].url	string	URL do video principal do item quando disponivel.	https://mms.vod.susercontent.com/video.mp4
executionId	string (uuid)	ID interno da execucao usado para observabilidade e dedupe.	66666666-2222-4222-8222-666666666666
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.	66666666-1111-4111-8111-666666666666

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.