Custos de envio e SLA

A gestão de custos de envio implica dois aspectos muito relevantes: o primeiro ocorre no momento de publicar ou editar um anúncio, enquanto o segundo ocorre no momento da compra.

Para a primeira fase, ou seja, no momento de publicar ou editar um anúncio, são necessários os seguintes endpoints:

Consultar produtos com envios gratuitos

O primeiro endpoint fornece as informações necessárias para verificar se o vendedor oferece envio gratuito em sua publicação.

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLA1122334488

Resposta com free shipping opcional:

    "shipping": {
        "mode": "me2",
        "methods": [],
        "tags": [
            "self_service_in"
        ],
        "dimensions": null,
        "local_pick_up": false,
        "free_shipping": true,
        "logistic_type": "cross_docking",
        "store_pick_up": false
    }

Lembre-se de que se a tag "mandatory_free_shipping" não estiver presente, o atributo "free_shipping" pode ser enviado como true ou false. Isso se deve ao fato de que o vendedor pode optar por oferecer ou não envios gratuitos de forma opcional.

Resposta com free shipping obrigatório:

    "shipping": {
        "mode": "me2",
        "methods": [],
        "tags": [
            "mandatory_free_shipping"
        ],
        "dimensions": null,
        "local_pick_up": true,
        "free_shipping": true,
        "logistic_type": "xd_drop_off",
        "store_pick_up": false
    }

• A tag “mandatory_free_shipping” se aplica exclusivamente a envios realizados através do Mercado Envios 2 (ME2).
• Caso o parâmetro "mandatory_free_shipping" esteja presente, o requisito é obrigatório. É crucial aderir a este parâmetro quando o endpoint o fornecer.
• Para Envios Turbo, a opção de "mandatory_free_shipping" não estará disponível. Em seu lugar, o Mercado Livre oferecerá um desconto conforme necessário.

Resposta com free shipping fora de ME2:

   "shipping": {
        "mode": "not_specified",
        "methods": [],
        "tags": [],
        "dimensions": null,
        "local_pick_up": true,
        "free_shipping": true,
        "logistic_type": "not_specified",
        "store_pick_up": false
    }

Em modalidades de envio que não correspondem a ME2, os vendedores têm a liberdade de definir o custo de envio conforme suas preferências.

Parâmetros de Resposta:

• shipping.mode: Modalidade de envio configurado para o item.
• shipping.tags: Tags de envio do item.

• Se indicar "mandatory_free_shipping" significa que o item superou o limite de preço estabelecido pelo Mercado Livre. Para esses produtos, o envio gratuito é uma obrigação. Os vendedores devem oferecer envios gratuitos ou descontos importantes no envio.
• Em contraste, para produtos com preço abaixo desse limite, o envio gratuito é opcional.

• shipping.dimensions: Dimensões do produto no formato: altura x largura x comprimento e peso.
• shipping.local_pick_u: Indicador booleano que mostra se a opção de retirada em pessoa está disponível.
• shipping.free_shipping: Indicador booleano que mostra se a opção de retirada em pessoa está disponível.
• shipping.logistic_type: Tipo de logística do envio.
• shipping.store_pick_up: Indicador booleano que mostra se a opção de retirada na loja está disponível.

Para obter uma visão mais detalhada sobre o limite de preços para envios gratuitos, convidamos você a consultar as seguintes páginas:

• Custos por oferecer envios gratuitos no Brasil
• Custos por oferecer envios gratuitos na Argentina
• Custos por oferecer envios gratuitos no México
• Custos por oferecer envios gratuitos no Chile
• Custos por oferecer envios gratuitos na Colômbia
• Custos por oferecer envios gratuitos no Peru
• Custos por oferecer envios gratuitos no Uruguai
• Custos por oferecer envios gratuitos no Equador

Consultar custos de envios de um item

Este endpoint permite conhecer o preço aproximado que o vendedor pagará pelo envio de um determinado item. Pode ser utilizado também para simular custos de envios ao publicar ou editar um item.

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'https://api.mercadolibre.com/users/$USER_ID/shipping_options/free?dimensions=$DIMENSIONS&verbose=$VERBOSE&item_price=$ITEM_PRICE&listing_type_id=$LISTING_TYPE&mode=$MODE&condition=$CONDITION&logistic_type=$LOGISTIC_TYPE

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'https://api.mercadolibre.com/users/244878077/shipping_options/free?dimensions=9x17x22,462&verbose=true&item_price=300&listing_type_id=gold_pro&mode=me2&condition=new&logistic_type=drop_off

Parâmetros de consulta aceitáveis:

Resposta:

{
"coverage": {
    "all_country": {
        "list_cost": 8106.49,
        "currency_id": "ARS",
        "billable_weight": 5828
    }
}
}

Parâmetros de resposta:

• coverage: Representa a cobertura de envio e contém informações sobre os custos e a moeda utilizada para o envio.
• coverage.all_country: Dentro de "coverage", "all_country" especifica que a informação se aplica a envios para todo o país.
• coverage.all_country.list_cost: Custo de envio oferecido ao vendedor.
• coverage.all_country.currency_id: Moeda utilizada para o custo de envio.
• coverage.all_country.billable_weight: Peso faturável do envio.
• coverage.discount: Informação sobre descontos aplicados ao envio.
• coverage.discount.rate: Taxa de desconto aplicada.
• coverage.discount.type: Descreve o tipo de desconto.
• coverage.discount.promoted_amount: Montante ou valor base sobre o qual se aplicará um certo percentual de desconto. Por exemplo, se temos um custo de envio de R$200 e se aplica um desconto de 40%, na resposta final obterá: list_cost = 120, rate: 0.4 e promoted_amount = 200.

Códigos de estado de resposta:

Em relação ao Mercado Shops, é importante destacar que atualmente não contamos com um endpoint específico para consultar os custos de envios. No entanto, queremos fornecer valiosas informações relacionadas às regras de negócio que se aplicam, bem como os montantes ou limites estabelecidos para oferecer envios gratuitos:

• Costos por oferecer envíos gratis en Brasil
• Costos por oferecer envíos gratis en Argentina
• Costos por oferecer envíos gratis en México
• Costos por oferecer envíos gratis en Chile
• Costos por oferecer envíos gratis en Colômbia

Para a segunda fase, ou o processo de compra de um anúncio, você deve utilizar os seguintes endpoints:

Consultar custos de envios ao comprar em um anúncio

Este endpoint proporciona uma visão detalhada das opções de envio disponíveis juntamente com seus custos no momento da compra de um anúncio, adaptando-se ao destino do comprador.

Chamada por CEP:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/shipping_options?zip_code=$ZIP_CODE

Exemplo por CEP:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLA1398714241/shipping_options?zip_code=1675

Chamada por Cidade:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/shipping_options?city_to=$CITY_TO

Exemplo por Cidade:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLA1398714241/shipping_options?city_to=Q08tRENCb2dvdA

Resposta:

{
"destination": {
    "zip_code": "1675",
    "city": {
        "id": null,
        "name": null
    },
    "state": {
        "id": "AR-B",
        "name": "Buenos Aires"
    },
    "country": {
        "id": "AR",
        "name": "Argentina"
    }
},
"buyer": {
    "id": 0,
    "loyalty_level": 1,
    "shipping_level": "1"
},
"options": [
    {
        "id": 3048556710,
        "option_hash": "708dd0837f1b1b6468c85d7079091889",
        "name": "Prioritario a domicilio",
        "currency_id": "ARS",
        "base_cost": 6023.99,
        "cost": 6023.99,
        "list_cost": 6023.99,
        "display": "recommended",
        "shipping_method_id": 510445,
        "shipping_method_type": "next_day",
        "shipping_option_type": "address",
        "estimated_delivery_time": {
            "type": "known",
            "date": "2024-04-20T00:00:00-03:00",
            "unit": "hour",
            "offset": {
                "date": null,
                "shipping": null
            },
            "time_frame": {
                "from": null,
                "to": null
            },
            "pay_before": "2024-04-20T14:00:00-03:00",
            "shipping": 0,
            "handling": 0,
            "schedule": null
        },
        "discount": {
            "promoted_amount": 0,
            "rate": 0,
            "type": "none",
            "show_loyal_benefit": false
        }
    },
    {
        "id": 1638980834,
        "option_hash": "0f1d5344a6cded1656403bfb6b4dbf50",
        "name": "Estándar a domicilio",
        "currency_id": "ARS",
        "base_cost": 6023.99,
        "cost": 6023.99,
        "list_cost": 6023.99,
        "display": "always",
        "shipping_method_id": 510645,
        "shipping_method_type": "three_days",
        "shipping_option_type": "address",
        "estimated_delivery_time": {
            "type": "known",
            "date": "2024-04-22T00:00:00-03:00",
            "unit": "hour",
            "offset": {
                "date": null,
                "shipping": null
            },
            "time_frame": {
                "from": null,
                "to": null
            },
            "pay_before": "2024-04-22T16:00:00-03:00",
            "shipping": 0,
            "handling": 0,
            "schedule": null
        },
        "discount": {
            "promoted_amount": 0,
            "rate": 0,
            "type": "none",
            "show_loyal_benefit": false
        }
    },
    {
        "id": 336095950,
        "option_hash": "027577b20d617392425136c0528cfb74",
        "name": "Estándar a sucursal de correo",
        "currency_id": "ARS",
        "base_cost": 10051.99,
        "cost": 10051.99,
        "list_cost": 10051.99,
        "display": "always",
        "shipping_method_id": 504345,
        "shipping_method_type": "standard",
        "shipping_option_type": "agency",
        "estimated_delivery_time": {
            "type": "known_frame",
            "date": "2024-04-24T00:00:00-03:00",
            "unit": "hour",
            "offset": {
                "date": "2024-04-29T00:00:00-03:00",
                "shipping": 72
            },
            "time_frame": {
                "from": null,
                "to": null
            },
            "pay_before": "2024-04-20T00:00:00-03:00",
            "shipping": 24,
            "handling": 48,
            "schedule": null
        },
        "discount": {
            "promoted_amount": 0,
            "rate": 0,
            "type": "none",
            "show_loyal_benefit": false
        }
    },
    {
        "id": 3594424224,
        "option_hash": "6f2e2eb2926b9e6a11c45fe07e9b8803",
        "name": "Estándar a domicilio",
        "currency_id": "ARS",
        "base_cost": 11409.99,
        "cost": 11409.99,
        "list_cost": 11409.99,
        "display": "optional",
        "shipping_method_id": 73328,
        "shipping_method_type": "standard",
        "shipping_option_type": "address",
        "estimated_delivery_time": {
            "type": "known_frame",
            "date": "2024-04-24T00:00:00-03:00",
            "unit": "hour",
            "offset": {
                "date": "2024-04-29T00:00:00-03:00",
                "shipping": 72
            },
            "time_frame": {
                "from": null,
                "to": null
            },
            "pay_before": "2024-04-20T00:00:00-03:00",
            "shipping": 24,
            "handling": 48,
            "schedule": null
        },
        "discount": {
            "promoted_amount": 0,
            "rate": 0,
            "type": "none",
            "show_loyal_benefit": false
        }
    }
],
"custom_message": {
    "display_mode": null,
    "reason": ""
}
}

Parâmetros de resposta:

• destination: Informação sobre o destino do envio, incluindo o código postal, a cidade, o estado e o país.
• buyer: Informação do comprador, como sua identificação, nível de lealdade e envio.
• options: Informação das opções de envio.
• options.id: Identificador único da opção de envio.
• options.option_hash: Hash único que identifica a opção de envio.
• options.name: Nome ou alias do modo de envio.
• options.currency_id: Identificador da moeda utilizada para o custo do envio.
• options.base_cost: Custo base do envio.
• options.cost: Custo total do envio para o comprador, aplicando descontos.
• options.list_cost: Custo real do envio antes de aplicar descontos.
• options.display: Visualização da opção de envio, pode ter os valores “recommended” (recomendado), “always” (sempre) ou “optional” (opcional).
• options.shipping_method_id: Identificador do método de envio utilizado.
• options.shipping_method_type: Tipo de método de envio utilizado.
• options.shipping_option_type: Tipo de opção de envio utilizado: address (endereço), agency (agência) ou place (local).
• options.estimated_delivery_time: Informação sobre o tempo estimado de entrega, incluindo a data estimada e qualquer outra informação relevante.
• options.discount: Informação sobre desconto no envio.
• custom_message: Este campo é utilizado para devolver avisos especiais e questões externas ao Mercado Livre que possam afetar ou atrasar o envio.

Códigos de estado de Resposta:

Resposta:

{
  "destination": {
      "zip_code": "1675",
      "city": {
          "id": null,
          "name": null
      },
      "state": {
          "id": "AR-B",
          "name": "Buenos Aires"
      },
      "country": {
          "id": "AR",
          "name": "Argentina"
      }
  },
  "buyer": {
      "id": 0,
      "loyalty_level": 1,
      "shipping_level": "1"
  },
  "options": [
      {
          "id": 3048556710,
          "option_hash": "708dd0837f1b1b6468c85d7079091889",
          "name": "Prioritario a domicilio",
          "currency_id": "ARS",
          "base_cost": 6023.99,
          "cost": 6023.99,
          "list_cost": 6023.99,
          "display": "recommended",
          "shipping_method_id": 510445,
          "shipping_method_type": "next_day",
          "shipping_option_type": "address",
          "estimated_delivery_time": {
              "type": "known",
              "date": "2024-04-20T00:00:00-03:00",
              "unit": "hour",
              "offset": {
                  "date": null,
                  "shipping": null
              },
              "time_frame": {
                  "from": null,
                  "to": null
              },
              "pay_before": "2024-04-20T14:00:00-03:00",
              "shipping": 0,
              "handling": 0,
              "schedule": null
          },
          "discount": {
              "promoted_amount": 0,
              "rate": 0,
              "type": "none",
              "show_loyal_benefit": false
          }
      },
      {
          "id": 1638980834,
          "option_hash": "0f1d5344a6cded1656403bfb6b4dbf50",
          "name": "Estándar a domicilio",
          "currency_id": "ARS",
          "base_cost": 6023.99,
          "cost": 6023.99,
          "list_cost": 6023.99,
          "display": "always",
          "shipping_method_id": 510645,
          "shipping_method_type": "three_days",
          "shipping_option_type": "address",
          "estimated_delivery_time": {
              "type": "known",
              "date": "2024-04-22T00:00:00-03:00",
              "unit": "hour",
              "offset": {
                  "date": null,
                  "shipping": null
              },
              "time_frame": {
                  "from": null,
                  "to": null
              },
              "pay_before": "2024-04-22T16:00:00-03:00",
              "shipping": 0,
              "handling": 0,
              "schedule": null
          },
          "discount": {
              "promoted_amount": 0,
              "rate": 0,
              "type": "none",
              "show_loyal_benefit": false
          }
      },
      {
          "id": 336095950,
          "option_hash": "027577b20d617392425136c0528cfb74",
          "name": "Estándar a sucursal de correo",
          "currency_id": "ARS",
          "base_cost": 10051.99,
          "cost": 10051.99,
          "list_cost": 10051.99,
          "display": "always",
          "shipping_method_id": 504345,
          "shipping_method_type": "standard",
          "shipping_option_type": "agency",
          "estimated_delivery_time": {
              "type": "known_frame",
              "date": "2024-04-24T00:00:00-03:00",
              "unit": "hour",
              "offset": {
                  "date": "2024-04-29T00:00:00-03:00",
                  "shipping": 72
              },
              "time_frame": {
                  "from": null,
                  "to": null
              },
              "pay_before": "2024-04-20T00:00:00-03:00",
              "shipping": 24,
              "handling": 48,
              "schedule": null
          },
          "discount": {
              "promoted_amount": 0,
              "rate": 0,
              "type": "none",
              "show_loyal_benefit": false
          }
      },
      {
          "id": 3594424224,
          "option_hash": "6f2e2eb2926b9e6a11c45fe07e9b8803",
          "name": "Estándar a domicilio",
          "currency_id": "ARS",
          "base_cost": 11409.99,
          "cost": 11409.99,
          "list_cost": 11409.99,
          "display": "optional",
          "shipping_method_id": 73328,
          "shipping_method_type": "standard",
          "shipping_option_type": "address",
          "estimated_delivery_time": {
              "type": "known_frame",
              "date": "2024-04-24T00:00:00-03:00",
              "unit": "hour",
              "offset": {
                  "date": "2024-04-29T00:00:00-03:00",
                  "shipping": 72
              },
              "time_frame": {
                  "from": null,
                  "to": null
              },
              "pay_before": "2024-04-20T00:00:00-03:00",
              "shipping": 24,
              "handling": 48,
              "schedule": null
          },
          "discount": {
              "promoted_amount": 0,
              "rate": 0,
              "type": "none",
              "show_loyal_benefit": false
          }
      }
  ],
  "custom_message": {
      "display_mode": null,
      "reason": ""
  }
}

Parâmetros de resposta:

• destination: Informação sobre o destino do envio, incluindo o código postal, a cidade, o estado e o país.
• buyer: Informação do comprador, como sua identificação, nível de lealdade e nível de envio.
• options: Informação das opções de envio.
• options.id: Identificador único da opção de envio.
• options.option_hash: Hash único que identifica a opção de envio.
• options.name: Nome ou alias do modo de envio.
• options.currency_id: Identificador da moeda utilizada para o custo do envio.
• options.base_cost: Custo base do envio.
• options.cost: Custo total do envio para o comprador, aplicando descontos.
• options.list_cost: Custo real do envio antes de aplicar descontos.
• options.display: Visualização da opção de envio, pode ter os valores “recommended” (recomendado), “always” (sempre) ou “optional” (opcional).
• options.shipping_method_id: Identificador do método de envio utilizado.
• options.shipping_method_type: Tipo de método de envio utilizado.
• options.shipping_option_type: Tipo de opção de envio utilizado: address (endereço), agency (agência) ou place (local).
• options.estimated_delivery_time: Informação sobre o tempo estimado de entrega, incluindo a data estimada e qualquer outra informação relevante.
• options.discount: Informação sobre desconto no envio.
• custom_message: Este campo é utilizado para devolver avisos especiais e questões externas ao Mercado Livre que possam afetar ou atrasar o envio.

Códigos de estado de Resposta:

Data máxima de despacho (SLA)

Este endpoint fornece a data e a hora limite que os vendedores têm para despachar suas vendas a tempo, ou seja, sem que seja considerada uma demora.

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipments/$SHIPMENT_ID/sla

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipments/43416180080/sla

Resposta:

{
    "status": "on_time",
    "expected_date": "2024-05-22T23:59:59-03:00",
    "last_updated": "2024-05-21T17:16:04Z"
}

Parâmetros de Resposta:

• status: Indica o estado atual do envio. Pode ter valores como "on_time" (a tempo), "delayed" (atrasado), "early" (adiantado).
• expected_date: Data e hora limite para despachar o produto.
• last_updated: Representa a última vez que as informações do envio foram atualizadas.

Códigos de Estado de Resposta:

Saiba mais sobre o gerenciamento de despacho:

• Despachar a tempo: a chave para uma boa reputação
• O que é e como funciona a reputação
• O que é levado em conta para calcular a reputação
• Quanto tempo você tem para despachar suas vendas
• Como obter o destaque "Chega amanhã" em suas publicações
• Como enviar suas vendas usando as agências do Mercado Livre.