O que é Mercado Envios 2

Com esses guias, ajudaremos você a publicar um produto com o Mercado Envios 2 e gerenciar todo o processo de envio usando nossos recursos de API. Leve em conta que as dimensões dos pacotes são estipuladas pelo Mercado Livre e não podem ser alteradas pelo usuário. Se você deseja ativar o Mercado Envios 2, pode fazê-lo de cada país (Argentina, Brasil, Colômbia, México, Chile, Uruguai).





Conteúdos

→Tipos de logísticas
→Adicionar ME2 a um item
→Consultar a data de envio do produto
→Impressão de etiquetas de envio
→Tipos de etiquetas por site
→Consultar envio de carrinho
    ↳Calcular o valor total com envio


Tipos de logísticas

Os diferentes tipos de envio são:

  • Mercado Envios (drop_off): o vendedor imprime a etiqueta e faz o envio nos Correios. Além disso, você precisa considerar o status de envio. Sobre o faturamento: não é obrigatório, mas caso o vendedor necessite, é possível carregar a nota fiscal ou usar o faturador do Mercado Livre.
  • Mercado Envios Places (xd_drop_off): Somente em MLA, MLB, MCO e MLM.
  • Mercado Envios Coleta (cross_docking): Somente em MLA, MLB, MLM e MLU.
  • Mercado Envios Flex (self_services): Somente em MLA, MLB, MLC, MCO e MLU.
  • Mercado Envios Full (fulfillment): Somente em MLA, MLB, MLM, MLC e MCO.
Importante:
A partir de 26 de julho de 2021 começaremos com o proceso de ativação e obrigatoriedade do Mercado Envíos (me2 - “drop_off” ) no Peru.

Adicionar ME2 a um item

Exemplo:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN'  -H "Content-Type: application/json" -d 
{
    "title": "Item de teste",
    "category_id": "MLA91727",
    "price": 1200,
    "currency_id": "ARS",
    "available_quantity": 2,
    "buying_mode": "buy_it_now",
    "listing_type_id": "bronze",
    "condition": "new",
    "description": "test",
    "pictures": [
        {
            "source": "http://upload.wikimedia.org/wikipedia/commons/f/fd/Ray_Ban_Original_Wayfarer.jpg"
        },
        {
            "source": "http://en.wikipedia.org/wiki/File:Teashades.gif"
        }
    ],
   "shipping": {
   "mode": "me2",
   "local_pick_up": false,
   "free_shipping": false,
   "free_methods": []
 }
}
https://api.mercadolibre.com/items/$ITEM_ID

Leve em conta que para anunciar em categorias marcadas como Frágil, o usuário também deverá estar marcado como "frágil"; para tal, deverá ter um acordo comercial. Nas seguintes chamadas da API você deverá validar os campos como se mostra abaixo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$USER_ID/shipping_preferences

{
  "local_pick_up": false,
  "modes": [
    "custom",
    "not_specified",
    "me1",
    "me2"
  ],
  "trusted_user": true,
  "custom_calculator": false,
  "picking_type": "cross_docking",
  "thermal_printer": null,
  "option": "in",
  "tags": [
  ],
  "carrier_pickup": false,
  "items_combination": "enabled",
  "services": [
    311,
    591,
    671,
    801,
    881,
    1181,
    1191,
    136261
  ],
  "logistics": [
    { 
      "mode": "me1",
      "types": [
        {
          "type": "default",
          "carrier_pickup": [],
          "services": [
            21,
            23,
            22,
            11
          ],
          "default": true
        }
      ]
    },

      {"mode": "me2",
      "types": [
        {
          "type": "cross_docking",
          "carrier_pickup": [
            17501840
          ],
          "services": [
            311,
            591,
            671,
            801,
            881,
            1181,
            1191
          ],
          "default": false
        },
        {
          "type": "self_service",
          "carrier_pickup": [
          ],
          "services": [
            136261
          ],
          "default": false
        }
      ]
    },
    {
      "mode": "custom",
      "types": [
        {
          "type": "custom",
          "carrier_pickup": [
          ],
          "services": null,
          "default": true
        }
      ]
    },
    {
      "mode": "not_specified",
      "types": [
        {
          "type": "not_specified",
          "carrier_pickup": [
          ],
          "services": null,
          "default": true
        }
      ]
    }
  ],
  "content_declaration_disabled": false,
  "conciliation": {
    "type": null
  },
  "mandatory_invoice_data": false,
  "site_id": "MLA",
  "free_configurations": [
    {
      "condition": {
        "value": null,
        "type": "all"
      },
      "rule": {
        "default": true,
        "free_mode": "country",
        "value": null
      }
    }
  ],
  "mandatory_settings": {
  }
}

"restricted": true (API category)

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/categories/MCO7159/shipping_preferences
{
  "category_id": "MCO7159",
  "dimensions": {
    "weight": 50000,
    "height": 20,
    "width": 60,
    "length": 130
  },
  "logistics": [
    {
      "types": [
        "default"
      ],
      "mode": "me1"
    },
    {
      "types": [
        "drop_off",
        "xd_drop_off",
        "cross_docking",
        "fulfillment"
      ],
      "mode": "me2"
    },
    {
      "types": [
        "not_specified"
      ],
      "mode": "not_specified"
    },
    {
      "types": [
        "custom"
      ],
      "mode": "custom"
    }
  ],
  "restricted": true
}

Consultar a data de envio do produto

Importante:
Esta funcionalidade está disponível apenas no México.

Para não ultrapassar a capacidade das transportadoras (carriers) e que os compradores recebam os produtos em dia, é necessário que você verifique a data de envio dos produtos. Identifique os envios desse tipo realizando um GET para /shipments, incorporando o header 'X-Format-New: true' verificando o “buffering”.

Chamada:

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

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'X-Format-New: true' https://api.mercadolibre.com/shipments/40173236996

Resposta:

{
   "id":40173236996,
   "external_reference":null,
   "status":"pending",
   "substatus":"buffered",
   "date_created":"2020-10-20T10:08:30.000-04:00",
   "last_updated":"2020-10-20T15:09:22.000-04:00",
   "declared_value":7000,
   "dimensions":{
      "height":14,
      "width":19,
      "length":38,
      "weight":950
   },
   "logistic":{
      "direction":"forward",
      "mode":"me2",
      "type":"xd_drop_off"
   },
  []
   "lead_time":{
      "option_id":3628548109,
      "shipping_method":{
         "id":510545,
         "name":"Express a domicilio",
         "type":"two_days",
         "deliver_to":"address"
      },
      "currency_id":"ARS",
      "cost":0,
      "list_cost":504.99,
      "cost_type":"free",
      "service_id":831,
      "delivery_type":"estimated",
      "estimated_schedule_limit":{
         "date":null
      },
      "buffering":{
         "date":"2020-10-21T20:18:26.000Z" ---> Fecha que podrá realizar el envío
      },
      "estimated_delivery_time":{
         "type":"known",
         "date":"2020-10-22T00:00:00.000-03:00",
         "unit":"hour",
         "offset":{
            "date":null,
            "shipping":null
         },
         "time_frame":{
            "from":null,
            "to":null
         },
         "pay_before":"2020-10-21T00:00:00.000-03:00",
         "shipping":24,
         "handling":24,
         "schedule":null
      },
      "estimated_delivery_limit":{
         "date":null,
         "offset":null
      },
      "estimated_delivery_final":{
         "date":null,
         "offset":null
      },
      "estimated_delivery_extended":{
         "date":null,
         "offset":null
      },
      "estimated_handling_limit":{
         "date":"2020-10-21T00:00:00.000-03:00"
      }
   },
   "tags":[
      "test_shipment"
   ]
}

No campo buffering "date" o "buffering" estará a data correspondente que o produto deve ser despachado e nesse mesmo dia disponibilizaremos a etiqueta para impressão.

Notas:
- Para as vendas com envios DropShipping, Cross Docking e Cross Docking Drop Off, se o substatus for “buffered” você deve marcar o "buffering" e informar ao vendedor que ele poderá imprimir a etiqueta na data indicada no campo "date".

Impressão de etiquetas de envio

No processo de venda, quando o comprador concluir sua compra (checkout), o vendedor deverá imprimir a etiqueta pré-paga para fazer o envio. Essa etiqueta pode ser um arquivo PDF ou ZPL e pode ser obtida consultando o recurso shipment_labels..
Faça a seguinte chamada GET com a lista de IDs de envios (shipping_id) e um access token. Quando o status dos envios for ready_to_ship você saberá que o pagamento foi processado e a etiqueta pré-paga está disponível.

Nota:
Recomendamos consultar até 50 (cinquenta) shipment_ids. Se você exceder o valor máximo permitido, receberá um erro 400.

Para obter etiquetas em formato PDF, realize a seguinte chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipment_labels?shipment_ids=$SHIPPING_ID1,$SHIPPING_ID2&response_type=pdf

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipment_labels?shipment_ids=20178600648,20182100995&response_type=pdf

Se você deseja as etiquetas no formato ZPL, altere response_type=pdf pelo response_type=zpl2:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipment_labels?shipment_ids=$SHIPPING_ID&response_type=zpl2

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipment_labels?shipment_ids=20178600648&response_type=zpl2

Este recurso retorna um arquivo ZIP que inclui um PDF com o PLP e um arquivo TXT da Zebra Printer.

Nota:
Para reimprimir a etiqueta, execute o mesmo GET.

Tipos de etiquetas por site

Tipo de impressão Impressora Sites disponíveis Tipo de resposta Saída
PDF Impressora normal. Argentina (MLA), México (MLM), Brasil (MLB), Colômbia (MCO), Chile (MLC) e Uruguai (MLU). response_type=pdf Etiqueta PDF
ZPL2 Impressora térmica. Argentina (MLA), México (MLM), Brasil (MLB), Chile (MLC), Uruguai (MLU), Colômbia (MCO). response_type=pdf Arquivo zip com etiqueta no formato txt e resumo da impressão no formato PDF.

Consultar envio de carrinho

Importante:
Carrinho de compras está disponível para a Argentina, Brasil, México, Chile e Colômbia. Em breve no Uruguai.

Com o carrinho de compras, os compradores podem tirar mais proveito do frete. Quando eles estiverem visitando suas publicações, nós recomendaremos os seus outros produtos para eles adicionarem ao carrinho. Se comprarem vários produtos de você, os compradores podem obter frete grátis ou descontos no frete.

Com a atual estrutura do JSON de pedido, as informações de envio não estão mais disponíveis, apenas a identificação estará lá. Dessa forma, você pode obter informações adicionais no recurso / shipments.
Para trabalhar com o JSON atualizado, ao fazer o GET deve-se enviar o parâmetro "x-format-new: true". O resto da estrutura do recurso continuará funcionando da mesma forma, com algumas modificações que você deve levar em consideração.

Chamada:

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

Exemplo:

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

Resposta:

{
    "id": 2053577644,
    "date_created": "2019-06-13T09:20:02.000-04:00",
    "date_closed": "2019-06-13T09:20:08.000-04:00",
    "last_updated": "2019-06-13T09:20:08.000-04:00",
    "manufacturing_ending_date": null,
    "feedback": {
        "sale": null,
        "purchase": null
    },
    "mediations": [],
    "comments": null,
    "pack_id": 2000000101334825,
    "pickup_id": null,
    "order_request": {
        "return": null,
        "change": null
    },
    "fulfilled": null,
    "total_amount": 9.99,
    "paid_amount": 9.99,
    "coupon": {
        "id": null,
        "amount": 0
    },
    "expiration_date": "2019-07-11T09:20:08.000-04:00",
    "order_items": [
        
            "item": {
                "id": "MLB1226730704",
                "title": "Produto Teste - Não Ofertar",
                "category_id": "MLB11742",
                "variation_id": null,
                "seller_custom_field": null,
                "variation_attributes": [],
                "warranty": "12 months",
                "condition": "new",
                "seller_sku": null
            },
            "quantity": 1,
            "unit_price": 9.99,
            "full_unit_price": 9.99,
            "currency_id": "BRL",
            "manufacturing_days": null
        
    ],
    "currency_id": "BRL",
    "payments": [
        
            "id": 4863317779,
            "order_id": 2053577644,
            "payer_id": 419067349,
            "collector": {
                "id": 419059118
            },
            "card_id": null,
            "site_id": "MLB",
            "reason": "Produto Teste - Não Ofertar",
            "payment_method_id": "account_money",
            "currency_id": "BRL",
            "installments": 1,
            "issuer_id": null,
            "atm_transfer_reference": {
                "company_id": null,
                "transaction_id": null
            },
            "coupon_id": null,
            "activation_uri": null,
            "operation_type": "regular_payment",
            "payment_type": "account_money",
            "available_actions": [
                "refund"
            ],
            "status": "approved",
            "status_code": null,
            "status_detail": "accredited",
            "transaction_amount": 9.99,
            "taxes_amount": 0,
            "shipping_cost": 0,
            "coupon_amount": 0,
            "overpaid_amount": 0,
            "total_paid_amount": 9.99,
            "installment_amount": null,
            "deferred_period": null,
            "date_approved": "2019-06-13T09:20:07.000-04:00",
            "authorization_code": null,
            "transaction_order_id": null,
            "date_created": "2019-06-13T09:20:07.000-04:00",
            "date_last_modified": "2019-06-13T09:20:07.000-04:00"
        
    ],
    "shipping": {
        "id": 27987243797
    },
    "status": "paid",
    "status_detail": null,
    "tags": [
        "test_order",
        "pack_order",
        "paid"
    ],
    "buyer": {
        "id": 419067349,
        "nickname": "TT763866",
        "email": "ttest.6hqmq6+2-ogiydkmzvg43tmobx@mail.mercadolivre.com",        },
        "first_name": "Test",
        "last_name": "Test",
        "billing_info": {
            "doc_type": "CPF",
            "doc_number": "78525276200"
        
    },
    "seller": {
        "id": 419059118,
        "nickname": "TETE8288849",
        "email": "ttest.hpz2z6q+2-ogiydkmzvg43tmobs@mail.mercadolivre.com",
        "phone": {
            "area_code": "01",
            "extension": "",
            "number": "1111-1111",
            "verified": false
        },
        "alternative_phone": {
            "area_code": "",
            "extension": "",
            "number": ""
        },
        "first_name": "Test",
        "last_name": "Test"
    },
    "taxes": {
        "amount": null,
        "currency_id": null
    
}

A resposta não retorna o campo total_amount_with_shipping, que deve ser calculado.
Para entender a qual cada um dos parâmetros se refere, faça a seguinte chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/$ORDER_ID?options

Calcular o valor total com envio

Com nosso recurso orders você pode calcular o valor total com frete.


Considerações

  • A tag "pack_order" é gerada automaticamente para poder discriminar se o pedido está associado a um carrinho e não pode ser excluído pelo comprador ou vendedor.
  • O campo "pack_id" mostra o número do carrinho ao qual o pedido pertence.
  • Caso o pedido não esteja associado a um Carrinho de Compras e a transação esteja na modalidade "concordo com o vendedor", você não receberá mais um status to be agreed, mas o ID de envio virá diretamente como null. Isso lhe dará a orientação de que você deve entrar em contato com o comprador para entrar em um acordoo sobre a forma de envio.
  • Você terá apenas o ID de envio e, em seguida, procurará as informações nos novos recursos de Shipping
  • Existe a possibilidade de que, mesmo com um pedido, o envio demore a ser criado. Nesses casos, o ID será nulo até sua criação. Quando isso acontecer, você será notificado.
  • As tags "delivered/not delivered" não serão mais adicionadas automaticamente. Apenas existirá a marcar se o integrador realizar um PUT com a tag definida.
  • Os pedidos com status paid serão cancelados se o pagamento for recusado ou devolvido. Caso isso aconteça, você receberá uma notificação para que possa saber a mudança no status do pedido.
Importante:
O pedido ainda mostrará o campo "seller_custom_field", mas mostrará os dados carregados com os seguintes critérios usados​ para escolher as informações do SKU:
1- SELLER_SKU de atributos de variação
2- seller_custom_field de variação
3- SELLER_SKU de atributos de item
4- seller_custom_field de item.

Próximo: Calcular o custo do frete e o handling time

ou registre-se para receber as últimas notícias sobre nossa API