GeckoAPI
PT EN
Entrar Testar URL

// docs

TikTok Shop PDP

Consulte um produto do TikTok Shop em 10 países por ID ou URL: preços, variantes, estoque informado, imagens, loja, avaliações, especificações e descrição quando disponível. Custo: 5 créditos por requisição bem-sucedida.

Sobre os dados: O produto deve pertencer ao país selecionado. Preços podem incluir ofertas e promoções. Estoque informado não garante disponibilidade no checkout. Descrição e outros campos opcionais podem retornar null; não representam uma falha quando os dados principais do produto estão disponíveis.

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.

Se a origem não fornecer um produto válido para o ID e o país selecionados, a consulta retorna erro de extração e não consome créditos. Esta API não converte respostas incompletas em produtos vazios ou em notFound.

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": "tiktok.com",
  "type": "pdp",
  "productId": "1737680778211985253",
  "region": "BR"
}'

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

tiktok_com_pdp

Auth

Bearer ou X-API-Key

tiktok_com_pdp tools/call 
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "tiktok_com_pdp",
    "arguments": {
      "productId": "1737680778211985253",
      "region": "BR",
      "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
productId
ID público do produto no TikTok Shop PDP. Pode substituir a URL; preserve como texto para evitar perda de precisão.
 string (10 a 25 dígitos) Condicional ID do produto como string com 10 a 25 dígitos. Obrigatório quando url não for informada. Pode ser copiado de data.items[].productId no PLP. Se enviar ambos, os IDs devem coincidir. - 1737680778211985253
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 HTTPS completa: tiktok.com/shop/[país/]pdp/[slug/]ID ou tiktok.com/view/product/ID. Aceita www.tiktok.com e shop.tiktok.com. Obrigatória se productId não for informado. Links encurtados e URLs de busca não são aceitos. - https://www.tiktok.com/shop/fr/pdp/1729905035780987763
region
Região da consulta. O formato depende da API; Temu PDP aceita br (Brasil), us (Estados Unidos), uk (Reino Unido) e co (Colômbia); PLP aceita br, us e uk. O padrão da Temu sem país na URL é br e OLX aceita uma região textual.
 string Opcional País do produto: BR, MX, JP, ID, MY, PH, SG, TH, VN ou FR. Aceita maiúsculas ou minúsculas. Quando omitido, usa o país da URL, se presente; caso contrário, BR. O país da URL deve coincidir com region. BR BR
target
Fonte alvo da extração.
 enum Obrigatório Use tiktok.com. - tiktok.com
type
Tipo da extração: pdp, idp, plp, ilp, quote, review ou places.
 enum Obrigatório Use pdp. - pdp

Exemplos de request

Produto por ID no Brasil

Use o productId retornado por uma busca PLP. Não precisa realizar uma busca antes desta consulta.

Produto por ID no Brasil 
{
  "target": "tiktok.com",
  "type": "pdp",
  "productId": "1737680778211985253",
  "region": "BR"
}

Produto por URL na França

URL completa de um produto do país selecionado. A resposta abaixo ilustra um produto francês com as listas resumidas.

Produto por URL na França 
{
  "target": "tiktok.com",
  "type": "pdp",
  "url": "https://www.tiktok.com/shop/fr/pdp/1729905035780987763",
  "region": "FR"
}

Schema de response (leaf paths)

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

responseSchema 
{
  "requestId": "string",
  "executionId": "string",
  "data.source": "\"tiktok.com\"",
  "data.type": "\"pdp\"",
  "data.region": "string",
  "data.currency": "string",
  "data.extractedAt": "string (ISO 8601)",
  "data.productId": "string",
  "data.url": "string (URL)",
  "data.name": "string",
  "data.status": "number | null",
  "data.priceType": "\"displayed_offer\"",
  "data.price": "number | null",
  "data.displayPrice": "string | null",
  "data.regularPrice": "number | null",
  "data.displayRegularPrice": "string | null",
  "data.minPrice": "number | null",
  "data.maxPrice": "number | null",
  "data.images": "array<object>",
  "data.images[].url": "string (URL)",
  "data.images[].width": "number | null",
  "data.images[].height": "number | null",
  "data.description": "object | null",
  "data.description.text": "string | null (optional)",
  "data.description.images": "array<object> (optional)",
  "data.description.images[].url": "string (URL) (optional)",
  "data.description.images[].width": "number | null (optional)",
  "data.description.images[].height": "number | null (optional)",
  "data.specifications": "array<object>",
  "data.specifications[].name": "string | null (optional)",
  "data.specifications[].value": "string | null (optional)",
  "data.category.id": "string | null",
  "data.category.name": "string | null",
  "data.seller.id": "string | null",
  "data.seller.name": "string | null",
  "data.seller.location": "string | null",
  "data.seller.rating": "number | null",
  "data.seller.productCount": "number | null",
  "data.soldCount": "number | null",
  "data.rating": "number | null",
  "data.reviewCount": "number | null",
  "data.variants": "array<object>",
  "data.variants[].skuId": "string",
  "data.variants[].status": "number | null",
  "data.variants[].price": "number | null",
  "data.variants[].displayPrice": "string | null",
  "data.variants[].regularPrice": "number | null",
  "data.variants[].displayRegularPrice": "string | null",
  "data.variants[].currency": "string | null",
  "data.variants[].stock": "number | null",
  "data.variants[].purchaseLimit": "number | null",
  "data.variants[].minimumBuyQuantity": "number | null",
  "data.variants[].attributes": "array<object>",
  "data.variants[].attributes[].name": "string | null (optional)",
  "data.variants[].attributes[].value": "string | null (optional)"
}

Exemplo de response

responseExample 
{
  "requestId": "req_tiktok_pdp_example",
  "executionId": "exec_tiktok_pdp_example",
  "data": {
    "source": "tiktok.com",
    "type": "pdp",
    "region": "FR",
    "currency": "EUR",
    "extractedAt": "2026-09-30T18:33:50.310708+00:00",
    "productId": "1729905035780987763",
    "url": "https://www.tiktok.com/shop/fr/pdp/1729905035780987763",
    "name": "Ensemble deux pièces de sac à main léger, grande capacité, couleur unie élégante et tendance, design minimaliste, nouveauté, idéal pour les trajets domicile‑travail",
    "status": 1,
    "priceType": "displayed_offer",
    "price": 16.87,
    "displayPrice": "16,87 €",
    "regularPrice": null,
    "displayRegularPrice": null,
    "minPrice": 16.87,
    "maxPrice": null,
    "images": [
      {
        "url": "https://p16-oec-general.tiktokcdn-eu.com/tos-alisg-i-aphluv4xwc-sg/13370cee0e524d6b95abb6e83d984285~tplv-aphluv4xwc-crop-webp:1350:1800.webp?dr=11209&t=555f072d&ps=933b5bde&shp=7745054a&shcp=9b759fb9&idc=no1a&from=2001012042",
        "width": 1350,
        "height": 1800
      }
    ],
    "description": {
      "text": "Grande capacité et design léger.",
      "images": [
        {
          "url": "https://p16-oec-general.tiktokcdn-eu.com/tos-alisg-i-aphluv4xwc-sg/13370cee0e524d6b95abb6e83d984285~tplv-aphluv4xwc-resize-webp:800:1066.webp?dr=11204&t=555f072d&ps=933b5bde&shp=7745054a&shcp=9b759fb9&idc=no1a&from=2001012042",
          "width": 800,
          "height": 1066
        }
      ]
    },
    "specifications": [
      {
        "name": "Modèle",
        "value": "Solid"
      }
    ],
    "category": {
      "id": "824584",
      "name": "Bagages et sacs"
    },
    "seller": {
      "id": "8650405036874242931",
      "name": "Rupai 1",
      "location": "France",
      "rating": null,
      "productCount": 128
    },
    "soldCount": 94,
    "rating": 2.5,
    "reviewCount": 2,
    "variants": [
      {
        "skuId": "1729905035781053299",
        "status": 1,
        "price": 16.87,
        "displayPrice": "16,87 €",
        "regularPrice": null,
        "displayRegularPrice": null,
        "currency": "EUR",
        "stock": 299,
        "purchaseLimit": 200,
        "minimumBuyQuantity": 0,
        "attributes": [
          {
            "name": "Couleur",
            "value": "Brun café"
          },
          {
            "name": "Taille",
            "value": "Taille unique"
          }
        ]
      }
    ]
  }
}

Referência completa de campos

Path Tipo Descrição Exemplo
data.category.id string | null ID da categoria. 824584
data.category.name string | null Nome da categoria. Bagages et sacs
data.currency string Moeda local: BRL, EUR, MXN, JPY, IDR, MYR, PHP, SGD, THB ou VND. EUR
data.description object | null Descrição quando fornecida. Pode faltar mesmo quando o restante do produto está disponível. {"text":"Grande capacité et design léger.","images":[{"url":"https://p16-oec-general.tiktokcdn-eu.com/tos-alisg-i-aphluv4xwc-sg/13370cee0e524d6b95abb6e83d984285~tplv-aphluv4xwc-resize-webp:800:1066.webp?dr=11204&t=555f072d&ps=933b5bde&shp=7745054a&shcp=9b759fb9&idc=no1a&from=2001012042","width":800,"height":1066}]}
data.description.images array<object> (optional) Imagens incluídas na descrição. [{"url":"https://p16-oec-general.tiktokcdn-eu.com/tos-alisg-i-aphluv4xwc-sg/13370cee0e524d6b95abb6e83d984285~tplv-aphluv4xwc-resize-webp:800:1066.webp?dr=11204&t=555f072d&ps=933b5bde&shp=7745054a&shcp=9b759fb9&idc=no1a&from=2001012042","width":800,"height":1066}]
data.description.images[].height number | null (optional) Altura da imagem da descrição. 1066
data.description.images[].url string (URL) (optional) URL de uma imagem da descrição. https://p16-oec-general.tiktokcdn-eu.com/tos-alisg-i-aphluv4xwc-sg/13370cee0e524d6b95abb6e83d984285~tplv-aphluv4xwc-resize-webp:800:1066.webp?dr=11204&t=555f072d&ps=933b5bde&shp=7745054a&shcp=9b759fb9&idc=no1a&from=2001012042
data.description.images[].width number | null (optional) Largura da imagem da descrição. 800
data.description.text string | null (optional) Texto da descrição; null para descrições compostas apenas por imagens. Grande capacité et design léger.
data.displayPrice string | null Preço formatado pela origem. 16,87 €
data.displayRegularPrice string | null Preço de referência formatado. null
data.extractedAt string (ISO 8601) Data e hora da extração. 2026-09-30T18:33:50.310708+00:00
data.images array<object> Galeria do produto. [{"url":"https://p16-oec-general.tiktokcdn-eu.com/tos-alisg-i-aphluv4xwc-sg/13370cee0e524d6b95abb6e83d984285~tplv-aphluv4xwc-crop-webp:1350:1800.webp?dr=11209&t=555f072d&ps=933b5bde&shp=7745054a&shcp=9b759fb9&idc=no1a&from=2001012042","width":1350,"height":1800}]
data.images[].height number | null Altura informada em pixels. 1800
data.images[].url string (URL) Endereço da imagem; links da origem podem expirar. https://p16-oec-general.tiktokcdn-eu.com/tos-alisg-i-aphluv4xwc-sg/13370cee0e524d6b95abb6e83d984285~tplv-aphluv4xwc-crop-webp:1350:1800.webp?dr=11209&t=555f072d&ps=933b5bde&shp=7745054a&shcp=9b759fb9&idc=no1a&from=2001012042
data.images[].width number | null Largura informada em pixels. 1350
data.maxPrice number | null Maior preço informado; null quando a origem não fornece um intervalo. null
data.minPrice number | null Menor preço informado entre as variantes. 16.87
data.name string Título do produto. Ensemble deux pièces de sac à main léger, grande capacité, couleur unie élégante et tendance, design minimaliste, nouveauté, idéal pour les trajets domicile‑travail
data.price number | null Preço de venda exibido, em unidades da moeda local. 16.87
data.priceType "displayed_offer" Preço exibido ao visitante, que pode incluir promoções. displayed_offer
data.productId string ID exato do produto; mantenha como texto para preservar todos os dígitos. 1729905035780987763
data.rating number | null Nota agregada do produto. 2.5
data.region string País selecionado para o catálogo. FR
data.regularPrice number | null Preço de referência antes de descontos, quando informado. null
data.reviewCount number | null Quantidade de avaliações do produto. 2
data.seller.id string | null ID da loja. 8650405036874242931
data.seller.location string | null Localização pública da loja, quando informada. France
data.seller.name string | null Nome da loja. Rupai 1
data.seller.productCount number | null Quantidade de produtos informada pela loja. 128
data.seller.rating number | null Avaliação da loja. null
data.soldCount number | null Contagem de vendas informada para o produto. 94
data.source "tiktok.com" Fonte dos dados. tiktok.com
data.specifications array<object> Especificações fornecidas; array vazio quando ausentes. [{"name":"Modèle","value":"Solid"}]
data.specifications[].name string | null (optional) Nome da especificação. Modèle
data.specifications[].value string | null (optional) Valor da especificação. Solid
data.status number | null Código numérico de status informado pela origem; não é garantia de disponibilidade no checkout. 1
data.type "pdp" Consulta de um produto. pdp
data.url string (URL) URL canônica do produto no país consultado. https://www.tiktok.com/shop/fr/pdp/1729905035780987763
data.variants array<object> Variantes/SKUs do produto. [{"skuId":"1729905035781053299","status":1,"price":16.87,"displayPrice":"16,87 €","regularPrice":null,"displayRegularPrice":null,"currency":"EUR","stock":299,"purchaseLimit":200,"minimumBuyQuantity":0,"attributes":[{"name":"Couleur","value":"Brun café"},{"name":"Taille","value":"Taille unique"}]}]
data.variants[].attributes array<object> Opções da variante, como cor e tamanho. [{"name":"Couleur","value":"Brun café"},{"name":"Taille","value":"Taille unique"}]
data.variants[].attributes[].name string | null (optional) Nome da opção. Couleur
data.variants[].attributes[].value string | null (optional) Valor da opção. Brun café
data.variants[].currency string | null Moeda informada para o SKU. EUR
data.variants[].displayPrice string | null Preço formatado da variante. 16,87 €
data.variants[].displayRegularPrice string | null Preço de referência formatado da variante. null
data.variants[].minimumBuyQuantity number | null Quantidade mínima informada pela origem. 0
data.variants[].price number | null Preço de venda da variante. 16.87
data.variants[].purchaseLimit number | null Limite de compra informado. 200
data.variants[].regularPrice number | null Preço de referência da variante. null
data.variants[].skuId string ID exato do SKU. 1729905035781053299
data.variants[].status number | null Código de status do SKU informado pela origem. 1
data.variants[].stock number | null Estoque informado para o SKU; 0 significa zero informado e null significa desconhecido. Não confirma disponibilidade no checkout. 299
executionId string Identificador da execução. exec_tiktok_pdp_example
requestId string Identificador da requisição GeckoAPI. req_tiktok_pdp_example

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.