// docs

AliExpress PLP

Extrai listagem de produtos (PLP) do AliExpress por URL ou keyword. 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/w/wholesale-relogio.html",
  "target": "aliexpress.com",
  "type": "plp",
  "page": 1
}'

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_plp

Auth

Bearer ou X-API-Key

aliexpress_com_plp tools/call

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "aliexpress_com_plp",
    "arguments": {
      "url": "https://pt.aliexpress.com/w/wholesale-relogio.html",
      "page": 1,
      "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	Obrigatorio somente quando keyword nao for enviada.	-	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	Obrigatorio quando url nao for enviada.	-	iphone 15 pro max
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
page Paginacao. Em PLP inicia em 1; em review (MercadoLivre, Booking e Hoteis) inicia em 0.	integer	Opcional	Suportado para PLP; deve ser inteiro >= 1.	-	2

Exemplos de request

PLP por URL

Consulta de listagem informando uma URL pronta do AliExpress.

PLP por URL

{
  "url": "https://pt.aliexpress.com/w/wholesale-relogio.html",
  "target": "aliexpress.com",
  "type": "plp",
  "page": 1
}

PLP por keyword (sem url)

Gateway monta a URL de busca a partir da keyword.

PLP por keyword (sem url)

{
  "keyword": "relogio",
  "target": "aliexpress.com",
  "type": "plp",
  "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)",
  "data.source": "string",
  "data.type": "string",
  "data.url": "string",
  "data.requestUrl": "string",
  "data.extractedAt": "string (iso datetime)",
  "data.query": "string",
  "data.totalResults": "number",
  "data.primaryResults": "number",
  "data.page": "number",
  "data.resultsPerPage": "number",
  "data.offset": "number",
  "data.nextPage": "number",
  "data.nextPageUrl": "string",
  "data.items[].position": "number",
  "data.items[].url": "string",
  "data.items[].sku": "string",
  "data.items[].productId": "string",
  "data.items[].name": "string",
  "data.items[].currency": "string",
  "data.items[].currencyRaw": "string",
  "data.items[].price": "number",
  "data.items[].regularPrice": "number",
  "data.items[].discountPercentage": "number",
  "data.items[].aggregateRating.rating": "number",
  "data.items[].aggregateRating.reviewCount": "number",
  "data.items[].orders": "number",
  "data.items[].thumbnail": "string",
  "data.items[].images[].url": "string",
  "data.items[].sellerName": "string",
  "data.items[].sellerUrl": "string",
  "data.items[].sponsored": "boolean"
}

Exemplo de response

responseExample

{
  "requestId": "7a0c0e3f-7d85-4d9b-a57d-730527fb8f40",
  "executionId": "6dfd2e49-e431-4375-8db1-f3b1eeefdf28",
  "data": {
    "source": "aliexpress.com",
    "type": "plp",
    "url": "https://pt.aliexpress.com/w/wholesale-relogio.html",
    "requestUrl": "https://pt.aliexpress.com/w/wholesale-relogio.html",
    "extractedAt": "2026-03-28T14:00:00.000Z",
    "query": "relogio",
    "totalResults": 123505,
    "primaryResults": 60,
    "page": 1,
    "resultsPerPage": 60,
    "offset": 0,
    "nextPage": 2,
    "nextPageUrl": "https://pt.aliexpress.com/w/wholesale-relogio.html?page=2",
    "items": [
      {
        "position": 1,
        "url": "https://pt.aliexpress.com/item/1005008606965599.html",
        "sku": "1005008606965599",
        "productId": "1005008606965599",
        "name": "Novo relogio t10 ultr relogio inteligente masculino 49mm",
        "currency": "BRL",
        "currencyRaw": "R$",
        "price": 34.99,
        "regularPrice": 74.15,
        "discountPercentage": 52,
        "aggregateRating": {
          "rating": 4.3,
          "reviewCount": 0
        },
        "orders": 2246,
        "thumbnail": "https://ae-pic-a1.aliexpress-media.com/kf/S7feedf9731414a63ac9e1e072d53d122b.jpg",
        "images": [
          {
            "url": "https://ae-pic-a1.aliexpress-media.com/kf/S7feedf9731414a63ac9e1e072d53d122b.jpg"
          }
        ],
        "sellerName": "Loja Oficial T10",
        "sellerUrl": "https://pt.aliexpress.com/store/1100000000",
        "sponsored": false
      }
    ]
  }
}

Referência completa de campos

Path	Tipo	Descrição	Exemplo
data.extractedAt	string (iso datetime)	Timestamp ISO da extracao.	2026-03-28T14:00:00.000Z
data.items[].aggregateRating.rating	number	Nota agregada do produto.	4.3
data.items[].aggregateRating.reviewCount	number	Quantidade de reviews quando disponivel no card.	0
data.items[].currency	string	Codigo da moeda do item.	BRL
data.items[].currencyRaw	string	Simbolo de moeda exibido.	R$
data.items[].discountPercentage	number	Percentual de desconto reportado pela listagem.	52
data.items[].images[].url	string	Lista de imagens conhecidas no card do resultado.	https://ae-pic-a1.aliexpress-media.com/kf/S7feedf9731414a63ac9e1e072d53d122b.jpg
data.items[].name	string	Titulo do produto exibido na listagem.	Novo relogio t10 ultr relogio inteligente masculino 49mm
data.items[].orders	number	Quantidade aproximada de pedidos/vendas do produto.	2246
data.items[].position	number	Posicao do item dentro da pagina atual.	1
data.items[].price	number	Preco promocional/atual do item.	34.99
data.items[].productId	string	Product ID exposto pelo AliExpress.	1005008606965599
data.items[].regularPrice	number	Preco original do item quando presente.	74.15
data.items[].sellerName	string	Nome do seller quando o card expuser essa informacao.	Loja Oficial T10
data.items[].sellerUrl	string	URL do seller quando o card expuser essa informacao.	https://pt.aliexpress.com/store/1100000000
data.items[].sku	string	Identificador principal do item no marketplace.	1005008606965599
data.items[].sponsored	boolean	Marca de patrocinio quando disponivel no card.	false
data.items[].thumbnail	string	Thumbnail principal do produto.	https://ae-pic-a1.aliexpress-media.com/kf/S7feedf9731414a63ac9e1e072d53d122b.jpg
data.items[].url	string	URL canonica do produto.	https://pt.aliexpress.com/item/1005008606965599.html
data.nextPage	number	Numero da proxima pagina quando houver.	2
data.nextPageUrl	string	URL sugerida para a proxima pagina quando houver.	https://pt.aliexpress.com/w/wholesale-relogio.html?page=2
data.offset	number	Offset numerico equivalente ao inicio da pagina atual.	0
data.page	number	Pagina atual resolvida pelo backend.	1
data.primaryResults	number	Quantidade de itens extraidos na pagina atual.	60
data.query	string	Keyword resolvida para a busca quando identificada.	relogio
data.requestUrl	string	URL efetivamente usada para capturar a pagina renderizada.	https://pt.aliexpress.com/w/wholesale-relogio.html
data.resultsPerPage	number	Tamanho da pagina informado pelo resultado.	60
data.source	string	Target canonico da seam retornada.	aliexpress.com
data.totalResults	number	Quantidade total de resultados reportada pela pagina.	123505
data.type	string	Tipo de extracao executada (plp).	plp
data.url	string	URL base informada ou montada pelo gateway para a busca.	https://pt.aliexpress.com/w/wholesale-relogio.html
executionId	string (uuid)	ID interno da execucao usado para observabilidade e dedupe.	6dfd2e49-e431-4375-8db1-f3b1eeefdf28
requestId	string (uuid)	ID unico da requisicao na camada HTTP.	7a0c0e3f-7d85-4d9b-a57d-730527fb8f40

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.