GeckoAPI
PT EN
Entrar Testar URL

// docs

Mercado Livre PDP

Extrai dados completos de produto (PDP) do Mercado Livre, com CEP opcional para frete e prazo.

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://produto.mercadolivre.com.br/MLB-4196330777-acrilico-toque-de-seda-premium-leve-brilho-16l-suvinil-_JM",
  "target": "mercadolivre.com.br",
  "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

mercadolivre_com_br_pdp

Auth

Bearer ou X-API-Key

mercadolivre_com_br_pdp tools/call 
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "mercadolivre_com_br_pdp",
    "arguments": {
      "url": "https://produto.mercadolivre.com.br/MLB-4196330777-acrilico-toque-de-seda-premium-leve-brilho-16l-suvinil-_JM",
      "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://produto.mercadolivre.com.br/MLB-4196330777-acrilico-toque-de-seda-premium-leve-brilho-16l-suvinil-_JM
zipCode
CEP brasileiro usado em APIs com resolucao geografica automatica. A API aceita com ou sem hifen e normaliza para 8 digitos.
 string (CEP) Opcional CEP brasileiro opcional. Quando informado, a navegacao do PDP usa este CEP para carregar frete e prazo de entrega. - 01001-000
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, 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

Requisicao basica com URL canonica da pagina de produto.

PDP por URL 
{
  "url": "https://produto.mercadolivre.com.br/MLB-4196330777-acrilico-toque-de-seda-premium-leve-brilho-16l-suvinil-_JM",
  "target": "mercadolivre.com.br",
  "type": "pdp"
}

PDP por URL com CEP

Requisicao com CEP para carregar frete e prazo de entrega no PDP.

PDP por URL com CEP 
{
  "url": "https://produto.mercadolivre.com.br/MLB-4196330777-acrilico-toque-de-seda-premium-leve-brilho-16l-suvinil-_JM",
  "zipCode": "01001-000",
  "target": "mercadolivre.com.br",
  "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.isInternational": "boolean",
  "data.variants[]": "string",
  "data.cashPrice": "number",
  "data.canonicalUrl": "string",
  "data.price": "number",
  "data.additionalProperties[].name": "string",
  "data.additionalProperties[].value": "string",
  "data.regularPrice": "number",
  "data.sellerName": "string",
  "data.sellerLevel": "string",
  "data.freeShipping": "boolean",
  "data.itemCondition": "string",
  "data.stockQuantity": "number",
  "data.images[].url": "string",
  "data.brand.name": "string",
  "data.sellerType": "string",
  "data.soldCount": "number",
  "data.shippingFee": "number",
  "data.shippingEstimatedDeliveryText": "string",
  "data.shippingEstimatedDeliveryTimeMinDays": "number",
  "data.shippingEstimatedDeliveryTimeMaxDays": "number",
  "data.shippingDestinationZipCode": "string",
  "data.aggregateRating.ratingValue": "number",
  "data.aggregateRating.reviewCount": "number",
  "data.aggregateRating.bestRating": "number",
  "data.currency": "string",
  "data.currencyRaw": "string",
  "data.breadcrumbs[].name": "string",
  "data.breadcrumbs[].url": "string",
  "data.description": "string",
  "data.mainImage.url": "string",
  "data.sku": "string",
  "data.availability": "string",
  "data.isFullDelivery": "boolean",
  "data.name": "string",
  "data.url": "string",
  "data.otherSellers[].sellerName": "string",
  "data.otherSellers[].price": "number",
  "data.otherSellers[].sellerUrl": "string",
  "data.otherSellers[].sellerId": "string",
  "data.otherSellers[].reputationLevel": "string",
  "data.otherSellers[].powerSellerStatusTitle": "string",
  "data.sellerId": "string",
  "data.powerSellerStatusTitle": "string",
  "data.sellerUrl": "string",
  "data.installmentPrice": "string",
  "data.installmentCount": "number",
  "data.itemId": "string | null (optional)",
  "data.userProductId": "string | null (optional)",
  "data.familyId": "string | null (optional)",
  "data.installmentOptions[].paymentMethodId": "string | null",
  "data.installmentOptions[].issuer": "string | null",
  "data.installmentOptions[].count": "integer | null",
  "data.installmentOptions[].amount": "number | null",
  "data.installmentOptions[].total": "number | null",
  "data.installmentOptions[].interestFree": "boolean | null",
  "data.installmentOptions[].meliplusInstallments": "boolean | null",
  "data.installmentOptions[].additionalBankInterest": "boolean | null",
  "data.installmentOptions[].rank": "number | null",
  "data.variantOptions[].attributeId": "string | null (optional)",
  "data.variantOptions[].label": "string | null (optional)",
  "data.variantOptions[].selectedProductId": "string | null (optional)",
  "data.variantOptions[].selectedValue": "string | null (optional)",
  "data.variantOptions[].selectionPrompt": "string | null (optional)",
  "data.variantOptions[].options[].productId": "string | null (optional)",
  "data.variantOptions[].options[].attributeValueId": "string | null (optional)",
  "data.variantOptions[].options[].value": "string | null (optional)",
  "data.variantOptions[].options[].url": "string | null (optional)",
  "data.variantOptions[].options[].selected": "boolean | null (optional)",
  "data.variantOptions[].options[].decorationType": "string | null (optional)",
  "data.variantOptions[].options[].availabilityText": "string | null (optional)",
  "data.variantOptions[].options[].price": "number | null (optional)",
  "data.variantOptions[].options[].regularPrice": "number | null (optional)",
  "data.variantOptions[].options[].currency": "string | null (optional)",
  "data.variantOptions[].options[].pictureId": "string | null (optional)",
  "data.variantOptions[].options[].thumbnailUrl": "string | null (optional)",
  "data.variantOptions[].options[].measurementsText": "string | null (optional)",
  "data.variantOptions[].options[].requiredAttributes[]": "string (optional)",
  "data.installmentOptions": "array (optional)",
  "data.variantOptions": "array (optional)"
}

Exemplo de response

responseExample 
{
  "requestId": "11111111-1111-4111-8111-111111111111",
  "executionId": "11111111-2222-4222-8222-111111111111",
  "data": {
    "isInternational": false,
    "variants": [
      "https://produto.mercadolivre.com.br/MLB-4196330777-acrilico-toque-de-seda-premium-leve-brilho-16l-suvinil-_JM"
    ],
    "cashPrice": 620.21,
    "canonicalUrl": "https://produto.mercadolivre.com.br/MLB-4196330777-acrilico-toque-de-seda-premium-leve-brilho-16l-suvinil-_JM",
    "price": 620.21,
    "additionalProperties": [
      {
        "name": "Marca",
        "value": "Suvinil"
      }
    ],
    "regularPrice": 689,
    "sellerName": "Loja Oficial RN",
    "sellerLevel": "5_green",
    "freeShipping": true,
    "itemCondition": "new",
    "stockQuantity": 7,
    "images": [
      {
        "url": "https://http2.mlstatic.com/D_NQ_NP_904711-MLB91911673092_092025-O.webp"
      }
    ],
    "brand": {
      "name": "Suvinil"
    },
    "sellerType": "brand",
    "soldCount": 42,
    "shippingFee": 15.99,
    "shippingEstimatedDeliveryText": "Chegara domingo",
    "shippingEstimatedDeliveryTimeMinDays": 2,
    "shippingEstimatedDeliveryTimeMaxDays": 2,
    "shippingDestinationZipCode": "01001000",
    "aggregateRating": {
      "ratingValue": 4.8,
      "reviewCount": 125,
      "bestRating": 5
    },
    "currency": "BRL",
    "currencyRaw": "R$",
    "breadcrumbs": [
      {
        "name": "Construcao",
        "url": "https://www.mercadolivre.com.br/c/construcao"
      }
    ],
    "description": "Tinta acrilica premium com acabamento acetinado.",
    "mainImage": {
      "url": "https://http2.mlstatic.com/D_NQ_NP_904711-MLB91911673092_092025-O.webp"
    },
    "sku": "MLB-4196330777",
    "availability": "InStock",
    "isFullDelivery": true,
    "name": "Acrilico Toque de Seda Premium 16L",
    "url": "https://produto.mercadolivre.com.br/MLB-4196330777-acrilico-toque-de-seda-premium-leve-brilho-16l-suvinil-_JM",
    "otherSellers": [
      {
        "sellerName": "Casa da Tinta",
        "price": 629.9,
        "sellerUrl": "https://lista.mercadolivre.com.br/?seller_id=123456",
        "sellerId": "123456",
        "reputationLevel": "5_green",
        "powerSellerStatusTitle": "gold"
      }
    ],
    "sellerId": "1006734354",
    "powerSellerStatusTitle": "platinum",
    "sellerUrl": "https://lista.mercadolivre.com.br/?seller_id=1006734354",
    "installmentPrice": "719.64",
    "installmentCount": 12,
    "itemId": null,
    "userProductId": null,
    "familyId": null,
    "installmentOptions": [
      {
        "paymentMethodId": null,
        "issuer": null,
        "count": 12,
        "amount": null,
        "total": 719.64,
        "interestFree": null,
        "meliplusInstallments": null,
        "additionalBankInterest": null,
        "rank": null
      }
    ],
    "variantOptions": []
  }
}

Referência completa de campos

Path Tipo Descrição Exemplo
data.additionalProperties[].name string Campo data.additionalProperties[].name retornado no payload de resposta. Marca
data.additionalProperties[].value string Campo data.additionalProperties[].value retornado no payload de resposta. Suvinil
data.aggregateRating.bestRating number Campo data.aggregateRating.bestRating retornado no payload de resposta. 5
data.aggregateRating.ratingValue number Campo data.aggregateRating.ratingValue retornado no payload de resposta. 4.8
data.aggregateRating.reviewCount number Campo data.aggregateRating.reviewCount retornado no payload de resposta. 125
data.availability string Campo data.availability retornado no payload de resposta. InStock
data.brand.name string Campo data.brand.name retornado no payload de resposta. Suvinil
data.breadcrumbs[].name string Campo data.breadcrumbs[].name retornado no payload de resposta. Construcao
data.breadcrumbs[].url string Campo data.breadcrumbs[].url retornado no payload de resposta. https://www.mercadolivre.com.br/c/construcao
data.canonicalUrl string Campo data.canonicalUrl retornado no payload de resposta. https://produto.mercadolivre.com.br/MLB-4196330777-acrilico-toque-de-seda-premium-leve-brilho-16l-suvinil-_JM
data.cashPrice number Campo data.cashPrice retornado no payload de resposta. 620.21
data.currency string Campo data.currency retornado no payload de resposta. BRL
data.currencyRaw string Campo data.currencyRaw retornado no payload de resposta. R$
data.description string Campo data.description retornado no payload de resposta. Tinta acrilica premium com acabamento acetinado.
data.familyId string | null (optional) ID da família do produto em string, preservando precisão e formato. Campo novo e opcional. null
data.freeShipping boolean Campo data.freeShipping retornado no payload de resposta. true
data.images[].url string Campo data.images[].url retornado no payload de resposta. https://http2.mlstatic.com/D_NQ_NP_904711-MLB91911673092_092025-O.webp
data.installmentCount number Campo data.installmentCount retornado no payload de resposta. 12
data.installmentOptions array (optional) Condições de parcelamento publicadas no documento já carregado. Lista vazia quando ausentes; não representa todas as condições de cartão/banco. [{"paymentMethodId":null,"issuer":null,"count":12,"amount":null,"total":719.64,"interestFree":null,"meliplusInstallments":null,"additionalBankInterest":null,"rank":null}]
data.installmentOptions[].additionalBankInterest boolean | null Indicador is_additional_bank_interest do upstream. false não significa parcelamento sem juros; consultar interestFree. null
data.installmentOptions[].amount number | null Valor de uma parcela, na moeda do produto; null quando não informado. null
data.installmentOptions[].count integer | null Número de parcelas desta opção; null quando não informado. 12
data.installmentOptions[].interestFree boolean | null true: sem juros; false: com juros; null: informação ausente. Não inferir pela ausência de texto. null
data.installmentOptions[].issuer string | null Categoria do emissor informada pelo upstream, por exemplo CREDIT_CARD. null
data.installmentOptions[].meliplusInstallments boolean | null Indicador is_meliplus_installments publicado na página. null
data.installmentOptions[].paymentMethodId string | null Identificador do método recomendado publicado na página, por exemplo visa. null
data.installmentOptions[].rank number | null Posição/rank informado pelo upstream; não atribuir rank quando ausente. null
data.installmentOptions[].total number | null Valor total parcelado, na moeda do produto; null quando não informado. 719.64
data.installmentPrice string Campo data.installmentPrice retornado no payload de resposta. 719.64
data.isFullDelivery boolean Campo data.isFullDelivery retornado no payload de resposta. true
data.isInternational boolean Campo data.isInternational retornado no payload de resposta. false
data.itemCondition string Campo data.itemCondition retornado no payload de resposta. new
data.itemId string | null (optional) ID do anúncio/oferta do contexto principal, como MLB4732132463. Campo novo e opcional; não substitui sku. null
data.mainImage.url string Campo data.mainImage.url retornado no payload de resposta. https://http2.mlstatic.com/D_NQ_NP_904711-MLB91911673092_092025-O.webp
data.name string Campo data.name retornado no payload de resposta. Acrilico Toque de Seda Premium 16L
data.otherSellers[].powerSellerStatusTitle string Campo data.otherSellers[].powerSellerStatusTitle retornado no payload de resposta. gold
data.otherSellers[].price number Campo data.otherSellers[].price retornado no payload de resposta. 629.9
data.otherSellers[].reputationLevel string Campo data.otherSellers[].reputationLevel retornado no payload de resposta. 5_green
data.otherSellers[].sellerId string Campo data.otherSellers[].sellerId retornado no payload de resposta. 123456
data.otherSellers[].sellerName string Campo data.otherSellers[].sellerName retornado no payload de resposta. Casa da Tinta
data.otherSellers[].sellerUrl string Campo data.otherSellers[].sellerUrl retornado no payload de resposta. https://lista.mercadolivre.com.br/?seller_id=123456
data.powerSellerStatusTitle string Campo data.powerSellerStatusTitle retornado no payload de resposta. platinum
data.price number Campo data.price retornado no payload de resposta. 620.21
data.regularPrice number Campo data.regularPrice retornado no payload de resposta. 689
data.sellerId string Campo data.sellerId retornado no payload de resposta. 1006734354
data.sellerLevel string Campo data.sellerLevel retornado no payload de resposta. 5_green
data.sellerName string Campo data.sellerName retornado no payload de resposta. Loja Oficial RN
data.sellerType string Campo data.sellerType retornado no payload de resposta. brand
data.sellerUrl string Campo data.sellerUrl retornado no payload de resposta. https://lista.mercadolivre.com.br/?seller_id=1006734354
data.shippingDestinationZipCode string CEP de destino que o Mercado Livre aplicou aos dados de frete. 01001000
data.shippingEstimatedDeliveryText string Texto de prazo de entrega exibido pelo Mercado Livre para o CEP usado. Chegara domingo
data.shippingEstimatedDeliveryTimeMaxDays number Limite maximo do prazo de entrega em dias quando exposto. 2
data.shippingEstimatedDeliveryTimeMinDays number Limite minimo do prazo de entrega em dias quando exposto. 2
data.shippingFee number Valor do frete em BRL normalizado como decimal; 0 quando gratis e null quando nao exposto. 15.99
data.sku string Campo data.sku retornado no payload de resposta. MLB-4196330777
data.soldCount number Campo data.soldCount retornado no payload de resposta. 42
data.stockQuantity number Campo data.stockQuantity retornado no payload de resposta. 7
data.url string Campo data.url retornado no payload de resposta. https://produto.mercadolivre.com.br/MLB-4196330777-acrilico-toque-de-seda-premium-leve-brilho-16l-suvinil-_JM
data.userProductId string | null (optional) ID do produto de usuário/contexto da página, como MLBU4048143160. Campo novo e opcional. null
data.variantOptions array (optional) Opções agrupadas por atributo, preservando IDs e URLs publicados. Lista vazia quando ausentes; não representa a matriz completa de combinações. []
data.variantOptions[].attributeId string | null (optional) Eixo de variação, como COLOR ou SIZE. N/A
data.variantOptions[].label string | null (optional) Rótulo do picker conforme publicado na página. N/A
data.variantOptions[].options[].attributeValueId string | null (optional) attribute_id da opção publicado pelo upstream. N/A
data.variantOptions[].options[].availabilityText string | null (optional) Texto de disponibilidade da opção, quando publicado; não converter automaticamente em estoque quantitativo. N/A
data.variantOptions[].options[].currency string | null (optional) Código de moeda publicado no preço da opção; null se ausente. N/A
data.variantOptions[].options[].decorationType string | null (optional) Estado visual bruto do upstream, como SELECTED, NONE ou DISABLED. DISABLED não comprova estoque zero. N/A
data.variantOptions[].options[].measurementsText string | null (optional) Texto de medidas da opção, como o comprimento do pé em cm. N/A
data.variantOptions[].options[].pictureId string | null (optional) Identificador da imagem da opção, quando publicado. N/A
data.variantOptions[].options[].price number | null (optional) Preço desta opção, somente quando explicitamente publicado no picker; não copiar o preço principal. N/A
data.variantOptions[].options[].productId string | null (optional) ID do produto da opção. A presença do mesmo ID em grupos distintos não autoriza eliminar a opção. N/A
data.variantOptions[].options[].regularPrice number | null (optional) Preço original da opção, quando publicado. N/A
data.variantOptions[].options[].requiredAttributes[] string (optional) IDs de atributos adicionais indicados pelo picker para acessar outras opções. N/A
data.variantOptions[].options[].selected boolean | null (optional) Seleção explícita da opção na página; null se não for possível determinar. O ID da página, isoladamente, não indica seleção. N/A
data.variantOptions[].options[].thumbnailUrl string | null (optional) URL de miniatura disponível no HTML capturado; construir apenas a partir de configuração/URL publicada, sem baixar a imagem. N/A
data.variantOptions[].options[].url string | null (optional) Permalink da opção com parâmetros de atributos e seleção preservados. N/A
data.variantOptions[].options[].value string | null (optional) Nome da opção, como Preto/Dourado ou 37 BR. N/A
data.variantOptions[].selectedProductId string | null (optional) ID explicitamente selecionado neste eixo; null quando nenhuma opção estiver selecionada. N/A
data.variantOptions[].selectedValue string | null (optional) Valor selecionado neste eixo. Um placeholder como Escolha é representado por null. N/A
data.variantOptions[].selectionPrompt string | null (optional) Texto do picker quando nenhuma opção estiver selecionada, como Escolha. N/A
data.variants[] string Campo data.variants[] retornado no payload de resposta. https://produto.mercadolivre.com.br/MLB-4196330777-acrilico-toque-de-seda-premium-leve-brilho-16l-suvinil-_JM
executionId string (uuid) ID de execucao para rastreio e deduplicacao. 11111111-2222-4222-8222-111111111111
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. 11111111-1111-4111-8111-111111111111

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.

Continue neste cluster

API Mercado Livre

Escolha da integração, cobertura, código, JSON e limitações.

Monitoramento de preços

Caso de uso com PLP, PDP, snapshots e alertas.

Guia técnico de scraper

Arquitetura, bloqueios, manutenção e alternativa por API.

Chatbot e MCP

Conecte agentes aos endpoints sem expor a chave.