// docs

AliExpress PDP

Extrai dados completos de produto (PDP) do AliExpress com browser render. Custo: 5 creditos por request.

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.

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://pt.aliexpress.com/item/1005007515734290.html",
  "target": "aliexpress.com",
  "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

aliexpress_com_pdp

Auth

Bearer ou X-API-Key

aliexpress_com_pdp tools/call

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "aliexpress_com_pdp",
    "arguments": {
      "url": "https://pt.aliexpress.com/item/1005007515734290.html",
      "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 combinar com o seam.	-	mercadolivre.com.br
type Tipo da extração: pdp, idp, plp, review ou places.	enum	Obrigatório	Sempre obrigatorio no payload e deve combinar com o seam.	-	pdp

Exemplos de request

PDP por URL

Consulta basica para pagina de produto do AliExpress.

PDP por URL

{
  "url": "https://pt.aliexpress.com/item/1005007515734290.html",
  "target": "aliexpress.com",
  "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)",
  "data.isInternational": "boolean",
  "data.variants[]": "string",
  "data.shippingDetails[].shippingFee": "string",
  "data.shippingDetails[].shippingAvailability": "string",
  "data.shippingDetails[].shippingTime.type": "string",
  "data.shippingDetails[].shippingTime.minValue": "string | number",
  "data.shippingDetails[].shippingTime.maxValue": "string | number",
  "data.cashPrice": "number",
  "data.canonicalUrl": "string",
  "data.price": "number",
  "data.additionalProperties[].name": "string",
  "data.additionalProperties[].value": "string",
  "data.regularPrice": "number",
  "data.sellerName": "string",
  "data.itemCondition": "string",
  "data.images[].url": "string",
  "data.brand.name": "string",
  "data.aggregateRating.ratingValue": "number",
  "data.aggregateRating.bestRating": "number",
  "data.aggregateRating.reviewCount": "number",
  "data.currency": "string",
  "data.currencyRaw": "string",
  "data.breadcrumbs[].name": "string",
  "data.breadcrumbs[].url": "string",
  "data.description": "string",
  "data.descriptionHtml": "string",
  "data.mainImage.url": "string",
  "data.sku": "string",
  "data.availability": "string",
  "data.name": "string",
  "data.url": "string",
  "data.otherSellers[]": "array",
  "data.sellerId": "string",
  "data.sellerUrl": "string",
  "data.installmentPrice": "string",
  "data.installmentCount": "number",
  "data.sellerCountry": "string",
  "data.sellerState": "string",
  "data.orders": "number",
  "data.stock": "number",
  "data.sellerPositiveRate": "number",
  "data.sellerFollowers": "number"
}

Exemplo de response

responseExample

{
  "requestId": "a7cbe4a5-c2c8-4d2d-a4b6-6a0f6d67c4c7",
  "executionId": "7f6c74f6-7d8d-4d19-8f28-14d2a6e9d1d2",
  "data": {
    "isInternational": false,
    "variants": [
      "Sabor: Baunilha"
    ],
    "shippingDetails": [
      {
        "shippingFee": "10.76",
        "shippingAvailability": "Da Brasil",
        "shippingTime": {
          "type": "DeliveryDateRange",
          "minValue": "05 de Abr.",
          "maxValue": "09 de Abr."
        }
      }
    ],
    "cashPrice": 66.99,
    "canonicalUrl": "https://pt.aliexpress.com/item/1005007515734290.html",
    "price": 66.99,
    "additionalProperties": [
      {
        "name": "Nome da marca",
        "value": "Integralmedica"
      }
    ],
    "regularPrice": 66.99,
    "sellerName": "Magalu Store",
    "itemCondition": "NewCondition",
    "images": [
      {
        "url": "https://ae01.alicdn.com/kf/Sae3a38d10722473d97c1d032dcd94b04d.jpg"
      }
    ],
    "brand": {
      "name": "Integralmedica"
    },
    "aggregateRating": {
      "ratingValue": 4.4,
      "bestRating": 5,
      "reviewCount": 7
    },
    "currency": "BRL",
    "currencyRaw": "R$",
    "breadcrumbs": [
      {
        "name": "Inicio",
        "url": "https://pt.aliexpress.com/br_home.htm"
      }
    ],
    "description": "Compre Whey Protein Concentrado Integralmédica no Aliexpress.",
    "descriptionHtml": "<p>Compre Whey Protein Concentrado Integralmédica no Aliexpress.</p>",
    "mainImage": {
      "url": "https://ae01.alicdn.com/kf/Sae3a38d10722473d97c1d032dcd94b04d.jpg"
    },
    "sku": "1005007515734290",
    "availability": "InStock",
    "name": "Whey Protein Concentrado Integralmédica",
    "url": "https://pt.aliexpress.com/item/1005007515734290.html",
    "otherSellers": [
      {
        "sellerName": "Suplementos Express",
        "sellerUrl": "https://pt.aliexpress.com/store/2200000000"
      }
    ],
    "sellerId": "1103942193",
    "sellerUrl": "https://pt.aliexpress.com/store/1103942193",
    "installmentPrice": "22.33",
    "installmentCount": 3,
    "sellerCountry": "Brasil",
    "sellerState": "SP",
    "orders": 43,
    "stock": 1000,
    "sellerPositiveRate": 96.9,
    "sellerFollowers": 71000
  }
}

Referência completa de campos

Path	Tipo	Descrição	Exemplo
data.additionalProperties[].name	string	Nome de uma especificacao extraida do bloco de detalhes.	Nome da marca
data.additionalProperties[].value	string	Valor da especificacao correspondente.	Integralmedica
data.aggregateRating.bestRating	number	Nota maxima da escala.	5
data.aggregateRating.ratingValue	number	Nota media agregada.	4.4
data.aggregateRating.reviewCount	number	Quantidade de avaliacoes agregadas.	7
data.availability	string	Disponibilidade normalizada (InStock/OutOfStock).	InStock
data.brand.name	string	Marca do produto.	Integralmedica
data.breadcrumbs[].name	string	Nome do breadcrumb.	Inicio
data.breadcrumbs[].url	string	URL do breadcrumb.	https://pt.aliexpress.com/br_home.htm
data.canonicalUrl	string	URL canonica do produto.	https://pt.aliexpress.com/item/1005007515734290.html
data.cashPrice	number	Preco principal usado como referencia a vista.	66.99
data.currency	string	Codigo da moeda do preco capturado.	BRL
data.currencyRaw	string	Simbolo de moeda exibido para o usuario.	R$
data.description	string	Descricao textual resumida do item.	Compre Whey Protein Concentrado Integralmédica no Aliexpress.
data.descriptionHtml	string	Descricao em HTML simplificado quando disponivel.	<p>Compre Whey Protein Concentrado Integralmédica no Aliexpress.</p>
data.images[].url	string	URL de uma imagem do produto em tamanho util para integracao.	https://ae01.alicdn.com/kf/Sae3a38d10722473d97c1d032dcd94b04d.jpg
data.installmentCount	number	Quantidade de parcelas exibidas.	3
data.installmentPrice	string	Valor por parcela quando exibido no PDP.	22.33
data.isInternational	boolean	Indica se a oferta parece internacional com base no contexto de envio capturado.	false
data.itemCondition	string	Condicao do item quando disponivel no markup estruturado.	NewCondition
data.mainImage.url	string	Imagem principal do produto.	https://ae01.alicdn.com/kf/Sae3a38d10722473d97c1d032dcd94b04d.jpg
data.name	string	Titulo do produto.	Whey Protein Concentrado Integralmédica
data.orders	number	Quantidade aproximada de pedidos/vendas exibida na pagina.	43
data.otherSellers[]	array	Lista de outros sellers; atualmente vazia para esta integracao.	{"sellerName":"Suplementos Express","sellerUrl":"https://pt.aliexpress.com/store/2200000000"}
data.price	number	Preco atual do produto.	66.99
data.regularPrice	number	Preco regular/original quando identificado.	66.99
data.sellerCountry	string	Pais do seller quando identificado.	Brasil
data.sellerFollowers	number	Quantidade de seguidores da loja.	71000
data.sellerId	string	Identificador da loja/seller quando presente.	1103942193
data.sellerName	string	Nome da loja/seller.	Magalu Store
data.sellerPositiveRate	number	Percentual de avaliacoes positivas da loja.	96.9
data.sellerState	string	Estado/provincia do seller quando identificado.	SP
data.sellerUrl	string	URL da loja/seller.	https://pt.aliexpress.com/store/1103942193
data.shippingDetails[].shippingAvailability	string	Origem de envio exibida no PDP.	Da Brasil
data.shippingDetails[].shippingFee	string	Valor de frete em formato decimal string; 0 quando gratis.	10.76
data.shippingDetails[].shippingTime.maxValue	string \| number	Data ou quantidade maxima prometida quando houver intervalo.	09 de Abr.
data.shippingDetails[].shippingTime.minValue	string \| number	Data ou quantidade minima prometida.	05 de Abr.
data.shippingDetails[].shippingTime.type	string	Tipo de prazo modelado para o envio.	DeliveryDateRange
data.sku	string	Identificador principal do item no AliExpress.	1005007515734290
data.stock	number	Estoque disponivel informado no seletor de quantidade.	1000
data.url	string	URL efetivamente usada/retornada pela captura.	https://pt.aliexpress.com/item/1005007515734290.html
data.variants[]	string	Lista de variacoes replicadas; hoje retorna vazio quando nao ha mapeamento confiavel.	Sabor: Baunilha
executionId	string (uuid)	ID interno da execucao usado para observabilidade e dedupe.	7f6c74f6-7d8d-4d19-8f28-14d2a6e9d1d2
requestId	string (uuid)	ID unico da requisicao na camada HTTP.	a7cbe4a5-c2c8-4d2d-a4b6-6a0f6d67c4c7

Erros comuns

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.