GeckoAPI
Entrar Começar grátis

// docs

Magalu PLP

Extrai listagem de produtos (PLP) da Magalu via endpoint mobile nao renderizado, com paginação.

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://www.magazineluiza.com.br/busca/iphone-15-pro-max/",
  "target": "magazineluiza.com.br",
  "type": "plp",
  "page": 2
}'

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

magazineluiza_com_br_plp

Auth

Bearer ou X-API-Key

magazineluiza_com_br_plp tools/call 
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "magazineluiza_com_br_plp",
    "arguments": {
      "url": "https://www.magazineluiza.com.br/busca/iphone-15-pro-max/",
      "page": 2,
      "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
priceMin
Preço mínimo para busca no Zapimoveis PLP.
 integer Opcional Preco minimo em reais inteiros; convertido internamente para centavos no app API (filters[type=price].values[0]) e na URL publica (filters=price---min:max). - 1000
priceMax
Preço máximo para busca no Zapimoveis PLP.
 integer Opcional Preco maximo em reais inteiros; convertido internamente para centavos no app API (filters[type=price].values[1]); quando ausente, a API usa 9000000 centavos. - 2000
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, quote, 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

Informa a URL publica da busca da Magalu e pagina explicitamente.

PLP por URL 
{
  "url": "https://www.magazineluiza.com.br/busca/iphone-15-pro-max/",
  "target": "magazineluiza.com.br",
  "type": "plp",
  "page": 2
}

PLP por keyword (sem url)

Gateway monta a URL automaticamente a partir da keyword.

PLP por keyword (sem url) 
{
  "keyword": "iphone 15 pro max",
  "target": "magazineluiza.com.br",
  "type": "plp",
  "page": 1
}

PLP com faixa de preco

Busca por keyword com preco minimo e maximo.

PLP com faixa de preco 
{
  "keyword": "iphone",
  "target": "magazineluiza.com.br",
  "type": "plp",
  "page": 1,
  "priceMin": 400,
  "priceMax": 600
}

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.source": "string",
  "data.type": "string",
  "data.url": "string",
  "data.requestUrl": "string",
  "data.extractedAt": "string (iso datetime)",
  "data.query": "string",
  "data.page": "number",
  "data.totalPages": "number",
  "data.resultsPerPage": "number",
  "data.offset": "number",
  "data.nextPage": "number",
  "data.nextPageUrl": "string",
  "data.items[].url": "string",
  "data.items[].sku": "string",
  "data.items[].name": "string",
  "data.items[].brand": "string",
  "data.items[].currency": "string",
  "data.items[].currencyRaw": "string",
  "data.items[].price": "number",
  "data.items[].cashPrice": "number",
  "data.items[].regularPrice": "number",
  "data.items[].aggregateRating.rating": "number",
  "data.items[].aggregateRating.reviewCount": "number",
  "data.items[].sellerId": "string",
  "data.items[].sellerName": "string",
  "data.items[].thumbnail": "string"
}

Exemplo de response

responseExample 
{
  "requestId": "33333333-1111-4111-8111-333333333333",
  "executionId": "33333333-2222-4222-8222-333333333333",
  "data": {
    "source": "magazineluiza.com.br",
    "type": "plp",
    "url": "https://www.magazineluiza.com.br/busca/iphone-15-pro-max/",
    "requestUrl": "https://www.magazineluiza.com.br/busca/iphone-15-pro-max/?page=2",
    "extractedAt": "2026-04-08T19:45:00.000Z",
    "query": "iphone 15 pro max",
    "page": 2,
    "totalPages": 5,
    "resultsPerPage": 10,
    "offset": 10,
    "nextPage": 3,
    "nextPageUrl": "https://www.magazineluiza.com.br/busca/iphone-15-pro-max/?page=3",
    "items": [
      {
        "url": "https://www.magazineluiza.com.br/apple-iphone-15-128gb-azul-61-48mp-ios-5g/p/238034800/te/ip15/?seller_id=magazineluiza",
        "sku": "238034800",
        "name": "Apple iPhone 15 128GB Azul 6,1\" 48MP iOS 5G",
        "brand": "Apple",
        "currency": "BRL",
        "currencyRaw": "R$",
        "price": 4776.67,
        "cashPrice": 4299,
        "regularPrice": 7299,
        "aggregateRating": {
          "rating": 4.9,
          "reviewCount": 3951
        },
        "sellerId": "magazineluiza",
        "sellerName": "Magalu",
        "thumbnail": "https://a-static.mlcdn.com.br/1000x1000/sample.jpg"
      }
    ]
  }
}

Referência completa de campos

Path Tipo Descrição Exemplo
data.extractedAt string (iso datetime) Campo data.extractedAt retornado no payload de resposta. 2026-04-08T19:45:00.000Z
data.items[].aggregateRating.rating number Campo data.items[].aggregateRating.rating retornado no payload de resposta. 4.9
data.items[].aggregateRating.reviewCount number Campo data.items[].aggregateRating.reviewCount retornado no payload de resposta. 3951
data.items[].brand string Campo data.items[].brand retornado no payload de resposta. Apple
data.items[].cashPrice number Campo data.items[].cashPrice retornado no payload de resposta. 4299
data.items[].currency string Campo data.items[].currency retornado no payload de resposta. BRL
data.items[].currencyRaw string Campo data.items[].currencyRaw retornado no payload de resposta. R$
data.items[].name string Campo data.items[].name retornado no payload de resposta. Apple iPhone 15 128GB Azul 6,1" 48MP iOS 5G
data.items[].price number Campo data.items[].price retornado no payload de resposta. 4776.67
data.items[].regularPrice number Campo data.items[].regularPrice retornado no payload de resposta. 7299
data.items[].sellerId string Campo data.items[].sellerId retornado no payload de resposta. magazineluiza
data.items[].sellerName string Campo data.items[].sellerName retornado no payload de resposta. Magalu
data.items[].sku string Campo data.items[].sku retornado no payload de resposta. 238034800
data.items[].thumbnail string Campo data.items[].thumbnail retornado no payload de resposta. https://a-static.mlcdn.com.br/1000x1000/sample.jpg
data.items[].url string Campo data.items[].url retornado no payload de resposta. https://www.magazineluiza.com.br/apple-iphone-15-128gb-azul-61-48mp-ios-5g/p/238034800/te/ip15/?seller_id=magazineluiza
data.nextPage number Campo data.nextPage retornado no payload de resposta. 3
data.nextPageUrl string Campo data.nextPageUrl retornado no payload de resposta. https://www.magazineluiza.com.br/busca/iphone-15-pro-max/?page=3
data.offset number Campo data.offset retornado no payload de resposta. 10
data.page number Campo data.page retornado no payload de resposta. 2
data.query string Campo data.query retornado no payload de resposta. iphone 15 pro max
data.requestUrl string Campo data.requestUrl retornado no payload de resposta. https://www.magazineluiza.com.br/busca/iphone-15-pro-max/?page=2
data.resultsPerPage number Campo data.resultsPerPage retornado no payload de resposta. 10
data.source string Campo data.source retornado no payload de resposta. magazineluiza.com.br
data.totalPages number Campo data.totalPages retornado no payload de resposta. 5
data.type string Campo data.type retornado no payload de resposta. plp
data.url string Campo data.url retornado no payload de resposta. https://www.magazineluiza.com.br/busca/iphone-15-pro-max/
executionId string (uuid) ID de execucao para rastreio e deduplicacao. 33333333-2222-4222-8222-333333333333
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 no gateway. 33333333-1111-4111-8111-333333333333

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.