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).





Tipos de logísticas

Os diferentes tipos de envio são:

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á ativa na Argentina, Brasil, México e Chile.

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..
Antes de tentar obter a etiqueta, é importante verificar o campo "mode" e "type", porque nem toda logística me2 disponibiliza etiqueta para impressão, como por exemplo fulfillment, onde a etiqueta é impressa pelo Mercado Livre em nossos centros de distribuição.
Os campos estarão dentro do node logistic com as seguintes informações:
- "mode" deve ser sempre me2
- "type" os serviços que precisam de impressão de etiquetas são:

  • drop_off (Mercado Envios)
  • xd_drop_off (Mercado Envios Places)
  • cross_docking (Mercado Envios Coleta)
  • self_service (Mercado Envios Flex)
  • forward

Quando o status dos envios for ready_to_ship e substatus ready_to_print você saberá que o pagamento foi processado e a etiqueta pré-paga está disponível.

Quando os envios estiverem nos seguintes status ou substatus não serão geradas etiquetas. Você só deve solicitar etiquetas em estados válidos, caso contrário, receberá um erro 400.

Status:
  • pending
  • handling
  • shipped
  • delivered
  • not_delivered
  • cancelled

Substatus:
  • waiting_for_carrier_authorization
  • invoice_pending
  • dropped_off
  • picked_up
  • under_review
Nota:
Recomendamos consultar até 50 (cinquenta) shipment_ids no mesmo GET. 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), Uruguai (MLU) e Perú (MPE). response_type=pdf Etiqueta PDF
ZPL2 Impressora térmica. Argentina (MLA), México (MLM), Brasil (MLB), Chile (MLC), Uruguai (MLU), Colômbia (MCO) e Perú (MPE). 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

banner footer

Inscreva-se em nosso Newsletter

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