Página de produto

A partir da versão 1.4.0, o fetch de produto é um endpoint próprio. O /list continua sendo listagem (vários cards ou busca por tema). O /product devolve um único produto a partir da URL.

Autenticação em todos os exemplos: header x-api-key. Depois do 202, consulte o resultado em GET /v1/tasks/{task_id}/status.

Referência OpenAPI:

• Mercado Livre
• Amazon
• Shopee

/list vs /product

Não use /list em URL de produto: o /list procura cards e volta items: [].

Como o /product funciona

1. Você envia POST /v1/fetch/{platform}/product.
2. A API cria uma task assíncrona (202 + task_id).
3. O worker processa:
   • ML / Amazon: abre a URL no Playwright e aplica os selectors na página inteira.
   • Shopee: lê shopId/itemId da URL e chama productOfferV2 na Open API de afiliados.
4. O status da task traz items (0 ou 1), count, page_url e final_url.

|| nos seletores é fallback: tenta o primeiro CSS; se vazio, tenta o próximo.

Não misture plataforma, URL e seletores. Path + URL + (seletores, se Playwright) devem ser da mesma loja.

Comparativo

Mercado Livre

Endpoint: POST /v1/fetch/mercadolivre/product

Motor: Playwright na página de produto (PDP).

Quando usar: URL que abre direto no produto (canal de ofertas, WhatsApp, /p/MLB..., produto.mercadolivre.com.br/MLB-...).

Body: url + selectors (obrigatórios). link não precisa de seletor: a API preenche com a URL canônica da página.

curl --location "$BASE_URL/v1/fetch/mercadolivre/product" \
  --header "Content-Type: application/json" \
  --header "x-api-key: $API_KEY" \
  --data '{
  "url": "https://www.mercadolivre.com.br/lixeira-inteligente-16l-com-sensor-automatico-e-tampa-touch-branco/p/MLB66154165?pdp_filters=item_id%3AMLB4505827975&utm_source=whatsapp",
  "selectors": {
    "titulo": "h1.ui-pdp-title",
    "quantidade_avaliacoes": "span.ui-pdp-review__amount",
    "preco_antigo": "s.andes-money-amount--previous",
    "preco_atual": "span.andes-money-amount--weight-semibold||.andes-money-amount--cents-superscript",
    "preco": "span.andes-money-amount--weight-semibold .andes-money-amount__fraction||span.andes-money-amount--weight-semibold",
    "valor_parcelas": "span.ui-pdp-price__part__container span.andes-money-amount--cents-comma",
    "cores_disponivel": "span.ui-pdp-outside_variations__title__value",
    "descricao": "ul.ui-vpp-highlighted-specs__features-list",
    "quantidade_vendidos": "span.ui-pdp-subtitle",
    "loja_vendedora": "button.ui-pdp-seller__link-trigger||a.ui-pdp-seller__link-trigger",
    "imagem": "img.ui-pdp-image||.ui-pdp-gallery__figure img"
  }
}'

O que a API faz:

• Abre a URL no Chromium headless.
• Espera o título da PDP (h1.ui-pdp-title).
• Extrai cada chave dos seletores no documento (não em cards de relacionados).
• Completa campos vazios com JSON-LD / Open Graph, se existirem.
• Define link como a URL canônica do produto.

Resultado típico (GET /v1/tasks/{task_id}/status):

{
  "status": "completed",
  "result": {
    "items": [
      {
        "titulo": "Lixeira Inteligente 16L ...",
        "preco_atual": "14990",
        "preco": "149",
        "imagem": "https://http2.mlstatic.com/...",
        "link": "https://www.mercadolivre.com.br/.../p/MLB66154165"
      }
    ],
    "count": 1,
    "page_url": "https://www.mercadolivre.com.br/...",
    "final_url": "https://www.mercadolivre.com.br/..."
  }
}

Os nomes das chaves em items[0] são os mesmos que você mandou em selectors, mais link.

Amazon

Endpoint: POST /v1/fetch/amazon/product

Motor: o mesmo Playwright do ML. Só mudam a URL da loja e os seletores.

Quando usar: URL de produto Amazon (/dp/ASIN). Os seletores do Mercado Livre não funcionam aqui.

Body: url + selectors (obrigatórios). Cookies da conta Amazon no cofre entram automaticamente, se existirem.

curl --location "$BASE_URL/v1/fetch/amazon/product" \
  --header "Content-Type: application/json" \
  --header "x-api-key: $API_KEY" \
  --data '{
  "url": "https://www.amazon.com.br/Notebook-Dell-Inspiron-I15-I1300-A30P-Carbono/dp/B0FHCHBRGF",
  "selectors": {
    "titulo": "#productTitle",
    "quantidade_avaliacoes": "#acrCustomerReviewText",
    "avaliacao_estrelas": "#acrPopover .a-icon-alt",
    "preco_antigo": "span.apex-basisprice-value .a-offscreen||span.basisPrice .a-offscreen",
    "preco_atual": "span.apex-pricetopay-value .a-offscreen||#corePriceDisplay_desktop_feature_div .priceToPay .a-offscreen",
    "preco": "span.apex-pricetopay-value .a-price-whole||span.a-price-whole",
    "valor_parcela": "#installmentCalculatorCentral_feature_div .a-color-attainable.a-text-bold",
    "cores_disponivel": "#variation_color_name .selection||#twister_feature_div .a-declarative",
    "descricao": "#feature-bullets ul.a-unordered-list",
    "loja_vendedora": "#bylineInfo||#sellerProfileTriggerId",
    "imagem": "#landingImage||#imgTagWrapperId img"
  }
}'

O que a API faz:

• Abre a PDP da Amazon.
• Espera #productTitle / #ppd.
• Aplica os seletores na página.
• Preenche link com canonical ou a própria URL (/dp/...).
• JSON-LD / Open Graph entram só onde o CSS vier vazio.

Se a Amazon bloquear (captcha), a task falha com scraping_blocked_by_target_site. Nesse caso use POST /v1/fetch/amazon/html na mesma URL para ver o HTML real.

Shopee

Endpoint: POST /v1/fetch/shopee/product

Motor: Open API de afiliados (productOfferV2). Não usa Playwright nem seletores.

Quando usar: você tem a URL de um anúncio e quer os dados daquele item. Para vitrine por tema (“fone bluetooth”), continue usando POST /v1/fetch/shopee/list com keyword.

Pré-requisito: conta Shopee no cofre (POST /v1/accounts): affiliate_id = App ID, cookies = secret da Open API.

Body: só url. Sem keyword, sem selectors.

A Open API não aceita URL. A OmniLink extrai o ID que já está na URL e consulta por itemId.

Formatos aceitos:

https://shopee.com.br/product/{shopId}/{itemId}
https://shopee.com.br/Nome-do-Produto-i.{shopId}.{itemId}

Link curto (s.shopee.com.br/...) é resolvido (redirect) e depois o ID é extraído. O itemId é exclusivo daquele anúncio, não é nicho nem categoria.

curl --location "$BASE_URL/v1/fetch/shopee/product" \
  --header "Content-Type: application/json" \
  --header "x-api-key: $API_KEY" \
  --data '{
  "url": "https://shopee.com.br/product/12345/67890"
}'

O que a API faz:

1. Extrai shopId=12345 e itemId=67890 (ou segue o short link até achar esses IDs).
2. Chama productOfferV2(itemId: 67890, shopId: 12345).
3. Devolve no máximo 1 item no mesmo contrato do /list (titulo, preco, link, imagem; opcionalmente commission_rate, product_link, shop_id, item_id).

{
  "status": "completed",
  "result": {
    "items": [
      {
        "titulo": "Fone Bluetooth",
        "preco": "R$ 49.90",
        "link": "https://shope.ee/...",
        "imagem": "https://cf.shopee.com.br/file/...",
        "shop_id": "12345",
        "item_id": "67890"
      }
    ],
    "count": 1,
    "page_url": "https://shopee.com.br/product/12345/67890",
    "final_url": "https://shopee.com.br/product/12345/67890",
    "shop_id": "12345",
    "item_id": "67890"
  }
}

Se a Open API não encontrar o item no catálogo de ofertas da afiliação, count vem 0. Isso não é scrap bloqueado: o produto pode não estar disponível para afiliados.

Consultar a task

curl --location "$BASE_URL/v1/tasks/TASK_ID/status" \
  --header "x-api-key: $API_KEY"

status: pending → processing → completed ou failed.

Webhook: webhook_override no body ou webhook_url da conta da mesma plataforma. Assinatura X-Omnilink-Signature. Detalhes em Tasks e webhooks.