// docs

AliExpress PDP

Retorna o JSON bruto do endpoint de produto (PDP) do AliExpress, sem normalizacao de campos. 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.

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://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://pt.aliexpress.com/item/1005007515734290.html
target Fonte alvo da extração.	enum	Obrigatório	Sempre obrigatorio no payload e deve combinar com o seam.	-	aliexpress.com
type Tipo da extração: pdp, idp, plp, ilp, quote, 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)",
  "notFound": "boolean (optional; true when the upstream entity was not found and data is null)",
  "data": "object (raw AliExpress PDP endpoint JSON; upstream-defined schema)"
}

Exemplo de response

responseExample

{
  "requestId": "a7cbe4a5-c2c8-4d2d-a4b6-6a0f6d67c4c7",
  "executionId": "7f6c74f6-7d8d-4d19-8f28-14d2a6e9d1d2",
  "data": {
    "api": "mtop.aliexpress.mobile.gw.item.detail",
    "data": {
      "result": {
        "global": {
          "bizContext": {
            "itemInfo": {
              "itemId": "1005007515734290"
            }
          }
        },
        "components": []
      }
    },
    "ret": [
      "SUCCESS::调用成功"
    ],
    "v": "1.0"
  }
}

Referência completa de campos

Path	Tipo	Descrição	Exemplo
data	object (raw AliExpress PDP endpoint JSON; upstream-defined schema)	JSON bruto retornado pelo endpoint PDP do AliExpress. A estrutura e os campos internos sao controlados pelo upstream e podem mudar sem normalizacao pela Gecko API.	{"api":"mtop.aliexpress.mobile.gw.item.detail","data":{"result":{"global":{"bizContext":{"itemInfo":{"itemId":"1005007515734290"}}},"components":[]}},"ret":["SUCCESS::调用成功"],"v":"1.0"}
executionId	string (uuid)	ID interno da execucao usado para observabilidade e dedupe.	7f6c74f6-7d8d-4d19-8f28-14d2a6e9d1d2
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.	a7cbe4a5-c2c8-4d2d-a4b6-6a0f6d67c4c7

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.