Qué es Mercado Envíos 2

Con estas guías te ayudaremos a publicar un producto con Mercado Envíos 2 y manejar todo el proceso de envío utilizando los recursos de nuestra API. Recuerda que las dimensiones de los paquetes son estipuladas por Mercado Libre y no pueden ser manipuladas por el usuario. Si deseas activar Mercado Envíos 2, puedes hacer desde cada país (Argentina, Brasil, Colombia, México, Chile, Uruguay).





Contenidos

→Tipos de logísticas
→Agregar ME2 a un ítem
→Consultar fecha de envío del producto
→Imprime etiquetas de envío
→Tipos de etiquetas por site
→Consultar envíos de carrito
    ↳Calcular monto total con envío


Tipos de logísticas

Los diferentes tipos de envíos son:

  • Mercado Envíos (drop_off): el vendedor imprime la etiqueta y realiza el envío en el Correo. Además, debe tener en cuenta el estado de envío. Sobre la facturación: no es obligatoria pero en caso de que el vendedor necesite es posible cargar la factura o puede utilizar el facturador de Mercado Libre.
  • Mercado Envíos Places (xd_drop_off): Solo en MLA, MLB, MCO y MLM.
  • Mercado Envíos Coleta (cross_docking): Solo en MLA, MLB, MLM y MLU.
  • Mercado Envíos Flex (self_services): Solo en MLA, MLB, MLC, MCO y MLU.
  • Mercado Envíos Full (fulfillment): Solo en MLA, MLB, MLM, MLC y MCO.

Agregar ME2 a un ítem

Ejemplo:

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

Recuerda que para publicar en categorías que marcadas como Frágil, el usuario también deberá estar marcado como "frágil", para esto deberá tener un acuerdo comercial. En las siguientes llamadas de la API deberás validar los campos que se muestran a continuación:

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 fecha de envío del producto

Importante:
Esta funcionalidad está disponible sólo en México.

Para evitar sobrepasar la capacidad de los transportistas (carriers) y que los compradores reciban los productos a tiempo, es necesario que consultes la fecha de envío de los productos. Identifica los envíos de este tipo realizando un GET a /shipments, incorporando el header 'X-Format-New: true' verificando el nodo “buffering”.

Llamada:

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

Ejemplo:

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

Respuesta:

{
   "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"
   ]
}

En el campo buffering “date” del nodo “buffering” estará la fecha correspondiente que se tiene que despachar el paquete y ese mismo día disponibilizaremos la etiqueta para la impresión.

Notas:
- Para las ventas con envíos DropShipping, Cross Docking y Cross Docking Drop Off, si el substatus es “buffered” deberás chequear el nodo “buffering” y comunicarle al vendedor que podrá imprimir la etiqueta en la fecha mencionada en el campo “date”.

Imprime etiquetas de envío

En el proceso de venta, cuando el comprador finaliza su compra (checkout), el vendedor debe imprimir la etiqueta prepaga para realizar el envío. Esta etiqueta puede ser un archivo PDF o ZPL y puedes obtenerla consultando al recurso shipment_labels.
Realiza la siguiente llamada GET con la lista de IDs de envíos (shipping_id) y un access token. Cuando el estado de los envíos sea ready_to_ship sabrás que el pago fue procesado y la etiqueta prepaga está disponible.

Nota:
Te recomendamos consultar hasta 50 (cincuenta) shipment_ids. Si superas la cantidad máxima permitida, recibirás un error 400.

Para obtener etiquetas en formato PDF, realiza la siguiente llamada:

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

Ejemplo:

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

Si deseas las etiquetas en formato ZPL, cambia response_type=pdf por response_type=zpl2:

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

Ejemplo:

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

Este recurso devuelve un archivo ZIP que incluye un PDF con el PLP y un archivo TXT para impresora Zebra.

Nota:
Para reimprimir la etiqueta, realiza el mismo GET.

Tipos de etiquetas por site

Tipo de impresión Impresora Sites disponibles Tipo de respuesta Salida
PDF Impresora común. Argentina (MLA), México (MLM), Brasil (MLB), Colombia (MCO), Chile (MLC) y Uruguay (MLU). response_type=pdf Etiqueta PDF
ZPL2 Impresora térmica. Argentina (MLA), México (MLM), Brasil (MLB), Chile (MLC), Uruguay (MLU), Colombia (MCO). response_type=pdf Archivo zip con la etiqueta en formato txt y resumen de impresión en formato PDF.

Consultar envíos de carrito

Importante:
Carrito de compras está disponible en Argentina, Brasil, México, Chile y Colombia. Próximamente en Uruguay.

Con el carrito de compras, los compradores pueden aprovechar más los envíos. Cuando estén visitando tus publicaciones, les recomendaremos tus otros productos para que los agreguen al carrito. Si te compran varios productos, los compradores podrán tener envío gratis o descuentos en el envío.

Con la actual estructura del JSON de orders, la información del envío no está más disponible, solo estará la identificación. De esta manera, puedes conseguir la información adicional en el recurso /shipments.
Para trabajar con el JSON actualizado, al hacer el GET deberás enviar el parámetro "x-format-new: true". El resto de la estructura del recurso seguirá funcionando de la misma manera, con algunas modificaciones que deberás tener en cuenta.

Llamada:

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

Ejemplo:

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

Respuesta:

{
    "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
    
}

La respuesta no devuelve el campo total_amount_with_shipping, el cual debe ser calculado. Para entender a qué hace referencia cada uno de los parámetros realiza la siguiente llamada:

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

Calcular monto total con envío

Con nuestro recurso orders puedes calcular el monto total con envío.


Consideraciones

  • El tag “pack_order” se genera de manera automática para poder discriminar si la orden está asociada a un carrito y no podrá ser borrado por el comprador o el vendedor.
  • El campo "pack_id" muestra el número de carrito al cual pertenece la orden.
  • En caso que la orden no esté asociada a un Carrito de Compras y la transacción sea bajo la modalidad “acordar con el vendedor”, ya no recibirás un status to be agreed si no que directamente el shipping ID vendrá como nule. Eso te dará la pauta de que deberás entrar en contacto con el comprador para coordinar la forma de envío.
  • Solo contarás con el ID del envío, para luego ir a buscar la información a los nuevos recursos de Shipping.
  • Existe la posibilidad de que, aún existiendo una orden, el envío demore en crearse. En esos casos el ID será nulo hasta su creación. Cuando eso pase, serás notificado.
  • Los tags “delivered/not delivered” ya no se agregarán automáticamente. Solamente existirá la marca si el integrador realiza un PUT con el tag definido.
  • Las órdenes en status paid se cancelarán si se rechaza o devuelve el pago. Si sucede, recibirás una notificación para que puedas conocer el cambio en el estado de la orden.
Importante:
La Orden seguirá mostrando el campo "seller_custom_field", pero mostrará los datos cargados con los siguientes criterios usados para escoger la información de SKU:
1- SELLER_SKU de atributos de variación
2- seller_custom_field de variación
3- SELLER_SKU de atributos de item
4- seller_custom_field de item.

Siguiente: Costos de envío y handling time.

o regístrate para recibir las últimas novedades sobre nuestra API