// docs

Magalu Quote

Extrai cotacoes de frete da Magalu para um produto especifico por URL e CEP.

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.

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/apple-iphone-15-128gb-azul-61-48mp-ios-5g/p/238034800/te/ip15/",
  "target": "magazineluiza.com.br",
  "type": "quote",
  "zipCode": "01001-000"
}'

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_quote

Auth

Bearer ou X-API-Key

magazineluiza_com_br_quote tools/call

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "magazineluiza_com_br_quote",
    "arguments": {
      "url": "https://www.magazineluiza.com.br/apple-iphone-15-128gb-azul-61-48mp-ios-5g/p/238034800/te/ip15/",
      "zipCode": "01001-000",
      "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	URL publica da pagina de produto da Magalu. O worker extrai o productId do padrao /p/<productId>/ e respeita seller_id quando presente.	-	https://www.magazineluiza.com.br/apple-iphone-15-128gb-azul-61-48mp-ios-5g/p/238034800/te/ip15/
zipCode CEP brasileiro usado em APIs com resolucao geografica automatica. A API aceita com ou sem hifen e normaliza para 8 digitos.	string (CEP)	Obrigatório	CEP de destino no formato 00000-000 ou 8 digitos. O backend normaliza para 8 digitos antes de chamar /v1/shipments/{zipCode}.	-	01001-000
target Fonte alvo da extração.	enum	Obrigatório	Sempre obrigatorio no payload e deve ser magazineluiza.com.br.	magazineluiza.com.br	magazineluiza.com.br
type Tipo da extração: pdp, idp, plp, ilp, quote, review ou places.	enum	Obrigatório	Sempre obrigatorio no payload e deve ser quote.	quote	quote

Exemplos de request

Frete por produto e CEP

Calcula as opcoes de entrega para o SKU e seller resolvidos a partir da URL publica do produto.

Frete por produto e CEP

{
  "url": "https://www.magazineluiza.com.br/apple-iphone-15-128gb-azul-61-48mp-ios-5g/p/238034800/te/ip15/",
  "target": "magazineluiza.com.br",
  "type": "quote",
  "zipCode": "01001-000"
}

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.parser": "\"1.0.0\"",
  "data.url": "string",
  "data.requestUrl": "string",
  "data.extractedAt": "string (ISO 8601)",
  "data.sku": "string",
  "data.zipCode": "string",
  "data.responseZipCode": "string | null",
  "data.sellerId": "string",
  "data.sellerName": "string | null",
  "data.offerAvailable": "boolean | null",
  "data.offerPrice": "number | null",
  "data.offerRegularPrice": "number | null",
  "data.currency": "string",
  "data.shippingId": "string | null",
  "data.disclaimers": "string[]",
  "data.totalOptions": "integer",
  "data.options[].name": "string | null",
  "data.options[].id": "string | null",
  "data.options[].type": "string | null",
  "data.options[].priceText": "string | null",
  "data.options[].price": "number | null",
  "data.options[].currency": "string",
  "data.options[].deadlineText": "string | null",
  "data.options[].deadlineDays": "integer | null",
  "data.options[].deliveryDate": "string | null",
  "data.options[].available": "boolean | null",
  "data.options[].message": "string | null",
  "data.options[].iconUrl": "string | null",
  "data.options[].distributionCenter": "integer | null"
}

Exemplo de response

responseExample

{
  "requestId": "4c5e18d7-5b1d-41c0-9b9a-f9ab45d42c8b",
  "executionId": "a4360f20-c423-4c21-8fc8-8c9b72158498",
  "data": {
    "source": "magazineluiza.com.br",
    "type": "quote",
    "parser": "1.0.0",
    "url": "https://www.magazineluiza.com.br/apple-iphone-15-128gb-azul-61-48mp-ios-5g/p/238034800/te/ip15/",
    "requestUrl": "https://www.magazineluiza.com.br/apple-iphone-15-128gb-azul-61-48mp-ios-5g/p/238034800/te/ip15/",
    "extractedAt": "2026-06-03T00:00:00.000Z",
    "sku": "238034800",
    "zipCode": "01001000",
    "responseZipCode": "01001000",
    "sellerId": "magazineluiza",
    "sellerName": "Magalu",
    "offerAvailable": true,
    "offerPrice": 3999,
    "offerRegularPrice": 4599,
    "currency": "BRL",
    "shippingId": "ship-1",
    "disclaimers": [
      "Os prazos contam apos a confirmacao do pagamento."
    ],
    "totalOptions": 2,
    "options": [
      {
        "name": "Entrega padrao",
        "id": "conventional",
        "type": "conventional",
        "priceText": "0.00",
        "price": 0,
        "currency": "BRL",
        "deadlineText": "Receba ate segunda-feira",
        "deadlineDays": 3,
        "deliveryDate": "2026-06-08",
        "available": true,
        "message": "Para pagamentos confirmados hoje",
        "iconUrl": "https://a-static.mlcdn.com.br/icon.png",
        "distributionCenter": 1
      },
      {
        "name": "Retira Loja",
        "id": "store_pickup",
        "type": "store_pickup",
        "priceText": "0.00",
        "price": 0,
        "currency": "BRL",
        "deadlineText": "Retire a partir de hoje",
        "deadlineDays": 0,
        "deliveryDate": "2026-06-03",
        "available": true,
        "message": "Os prazos contam apos a confirmacao do pagamento.",
        "iconUrl": "https://a-static.mlcdn.com.br/pickup.png",
        "distributionCenter": 2
      }
    ]
  }
}

Referência completa de campos

Path	Tipo	Descrição	Exemplo
data.currency	string	Codigo da moeda normalizada.	BRL
data.disclaimers	string[]	Avisos gerais retornados pela cotacao de frete.	["Os prazos contam apos a confirmacao do pagamento."]
data.extractedAt	string (ISO 8601)	Timestamp ISO em que a extracao foi finalizada.	2026-06-03T00:00:00.000Z
data.offerAvailable	boolean \| null	Disponibilidade da variacao usada para montar a cotacao.	true
data.offerPrice	number \| null	Preco usado no campo value do replay de shipments.	3999
data.offerRegularPrice	number \| null	Preco de lista retornado pelo helper, quando presente.	4599
data.options[].available	boolean \| null	Disponibilidade da modalidade quando retornada.	true
data.options[].currency	string	Codigo da moeda normalizada.	BRL
data.options[].deadlineDays	integer \| null	Prazo em dias quando a origem expuser um campo numerico.	3
data.options[].deadlineText	string \| null	Prazo textual retornado pela origem.	Receba ate segunda-feira
data.options[].deliveryDate	string \| null	Data prevista de entrega quando retornada.	2026-06-08
data.options[].distributionCenter	integer \| null	Centro de distribuicao retornado pela origem quando presente.	1
data.options[].iconUrl	string \| null	Icone da modalidade quando retornado pela origem.	https://a-static.mlcdn.com.br/icon.png
data.options[].id	string \| null	Identificador da modalidade quando retornado.	conventional
data.options[].message	string \| null	Mensagem adicional da modalidade ou disclaimer geral.	Para pagamentos confirmados hoje
data.options[].name	string \| null	Nome da modalidade de entrega.	Entrega padrao
data.options[].price	number \| null	Preco numerico do frete em BRL.	0
data.options[].priceText	string \| null	Preco textual do frete antes da normalizacao.	0.00
data.options[].type	string \| null	Tipo tecnico da modalidade, como conventional ou store_pickup.	conventional
data.parser	"1.0.0"	Versão estável do formato de resposta da API.	1.0.0
data.requestUrl	string	Mesmo valor de `data.url`; nunca expõe o endpoint interno consultado.	https://www.magazineluiza.com.br/apple-iphone-15-128gb-azul-61-48mp-ios-5g/p/238034800/te/ip15/
data.responseZipCode	string \| null	CEP retornado pelo endpoint de shipments quando presente.	01001000
data.sellerId	string	Seller usado na cotacao de frete, resolvido a partir do helper PDP da Magalu.	magazineluiza
data.sellerName	string \| null	Nome do seller resolvido quando o helper expuser esse campo.	Magalu
data.shippingId	string \| null	Identificador retornado pelo objeto shipping quando presente.	ship-1
data.sku	string	SKU do produto usado na cotacao de frete.	238034800
data.source	string	Fonte normalizada da extracao.	magazineluiza.com.br
data.totalOptions	integer	Quantidade de opcoes de entrega normalizadas.	2
data.type	string	Tipo do seam executado.	quote
data.url	string	URL publica de produto enviada no request.	https://www.magazineluiza.com.br/apple-iphone-15-128gb-azul-61-48mp-ios-5g/p/238034800/te/ip15/
data.zipCode	string	CEP de destino normalizado para 8 digitos.	01001000
executionId	string (uuid)	Identificador unico da execucao do worker para rastreabilidade.	a4360f20-c423-4c21-8fc8-8c9b72158498
requestId	string (uuid)	Identificador unico do request HTTP na GeckoAPI.	4c5e18d7-5b1d-41c0-9b9a-f9ab45d42c8b

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.