Manejo de Envíos

El recurso de Shipments, contiene toda la información referida al envío que se debe realizar para concluir con la transacción. Nota: Recuerda que para trabajar con el JSON de shipments, al hacer el GET deberás enviar el parámetro "x-format-new: true".

Contenido:

Es importante tener en cuenta que el nuevo JSON de Orders no va contener los datos de Shipping, como sí viene haciendo hasta ahora. El recurso /shipments/shipment_id/ continuará con su estructura, mostrando la información básica para realizar el envío. Introducimos algunos cambios en la estructura del JSON, que podrás ver a continuación:
GET https://api.mercadolibre.com/shipments/shipment_id?access_token=token
{
  "id": 0,
  "external_reference": "string",
   "status": "string",
  "substatus": "string",
  "date_created": "string",
  "last_updated": "string",
  "declared_value": 0,
  "dimensions": {
    "height": 0,
    "width": 0,
    "length": 0,
    "weight": 0
  },
  "logistic": {
    "direction": "forward",
    "mode": "me2",
    "type": "drop_off"
  },
  "source": {
    "site_id": "MLM",
    "market_place": "MELI",
    "application_id": null
  },
  "tracking_number": "string",
  "origin": {
    "type": "selling_address",
    "sender_id": 0,
    "shipping_address": {
      "id": 0,
      "address_id": 0,
      "address_line": "string",
      "street_name": "string",
      "street_number": 0,
      "comment": "string",
      "zip_code": "string",
      "city": {
        "id": "string",
        "name": "string"
      },
      "state": {
        "id": "string",
        "name": "string"
      },
      "country": {
        "id": "string",
        "name": "string"
      },
      "neighborhood": {
        "id": "string",
        "name": "string"
      },
      "municipality": {
        "id": "string",
        "name": "string"
      },
      "types": {
        "default_buying_address": 0
      },
      "agency": {
        "carrier_id": 0,
        "agency_id": "string",
        "description": "string",
        "phone": "string",
        "open_hours": "string"
      },
      "latitude": 0,
      "longitude": 0,
      "geolocation_type": "string",
      "is_valid_for_carrier": true
    }
  },
  "destination": {
    "type": "buying_address",
    "receiver_id": 0,
    "receiver_name": "string",
    "receiver_phone": "string",
    "comments": "string",
    "shipping_address": {
      "id": 0,
      "address_id": 0,
      "address_line": "string",
      "street_name": "string",
      "street_number": 0,
      "comment": "string",
      "zip_code": "string",
      "city": {
        "id": "string",
        "name": "string"
      },
      "state": {
        "id": "string",
        "name": "string"
      },
      "country": {
        "id": "string",
        "name": "string"
      },
      "neighborhood": {
        "id": "string",
        "name": "string"
      },
      "municipality": {
        "id": "string",
        "name": "string"
      },
      "types": {
        "default_buying_address": 0
      },
      "agency": {
        "carrier_id": 0,
        "agency_id": "string",
        "description": "string",
        "phone": "string",
        "open_hours": "string"
      },
      "latitude": 0,
      "longitude": 0,
      "geolocation_type": "string",
      "is_valid_for_carrier": true
    }
  },
  "lead_time": {
    "option_id": 0,
    "shipping_method": {
      "id": 0,
      "type": "standard",
      "name": "string",
      "deliver_to": "address"
    },
    "currency_id": "string",
    "cost": 0,
    "cost_type": "charged",
    "service_id": 0,
    "estimated_delivery_time": {
      "type": "known",
      "date": "string",
      "shipping": 0,
      "handling": 0,
      "unit": "string",
      "offset": {
        "date": "string",
        "shipping": 0
      },
      "time_frame": {
        "from": 0,
        "to": 0
      },
      "pay_before": "string"
    }
  },
  "tags": [
    "string"
  ]
}
Para entender a qué hace referencia cada uno de los parámetros realiza la siguiente llamada:
GET https://api.mercadolibre.com/shipments/shipment_id?options&access_token=token
Nota: external_reference hace referencia al número de pack relacionado con el envío.

Nuevos recursos

Con la nueva versión del recurso Shipments, aparecen nuevos recursos complementarios que aportarán información detallada para poder trabajar de manera más eficiente. A continuación ampliaremos cada uno de ellos. Ver api docs de recursos existentes.

Items

El recurso /shipments/shipment_id/items devuelve los ítems asociados a un shipment. En caso de que el ítem contenga variaciones (Por ejemplo: talle o color en indumentaria), también podrás ver cual corresponde a la orden dentro del envío. A medida que habilitemos envíos con más de un ítem, la lista pasará a contener cada uno de ellos. Nota: Cada vendedor sólo visualizará sus propios productos.
GET https://api.mercadolibre.com/shipments/shipment_id/items

[
  {
    "item_id": "string",
    "description": "string",
    "quantity": 0,
    "variation_id": 0,
    "dimensions": {
      "height": 0,
      "width": 0,
      "length": 0,
      "weight": 0
    },
    "order_id": 0,
    "sender_id": 0
  }
]

Costs

El recurso /shipments/shipment_id/costs devuelve los costos del envío que deberá afrontar el usuario. También podrá visualizar el ahorro conseguido por el envío de más de un producto en la misma caja (cuando esté habilitada está funcionalidad), a través del parámetro “save”, en caso de que exista. Nota: Estamos trabajando en una nueva versión de este recurso. Durante la implementación de los cambios, se mantendrá la respuesta actual y para acceder al nuevo formato,explicado a continuación, deberá utilizarse el header "X-Costs-New = true".
GET https://api.mercadolibre.com/shipments/SHIPMENT_ID/costs?access_token=$ACCES_TOKEN 
{
	"gross_amount": 24.55,
	"receiver": {
    	"user_id": 74425755,
    	"cost": 0,
    	"compensation": 0,
    	"save": 0,
    	"discounts": [
        	{
            	"rate": 1,
            	"type": "loyal",
            	"promoted_amount": 4.07
        	}
    		]
	},
	"senders": [
    	{
        	"user_id": 81387353,
        	"cost": 8.19,
        	"compensation": 0,
        	"save": 0,
        	"discounts": [
            	{
                	"rate": 0.6,
                	"type": "mandatory",
                	"promoted_amount": 12.29
            	}
        	]
    	}
	]
}

Parámetros

  • "gross_amount": Es el costo total del shipment sin ningún tipo de descuento.
  • "discounts": representa una lista que puede venir vacía si no hay ningún descuento, y sino puede tener uno o más descuentos asociados.
  • "senders": es una lista adaptada a versiones futuras de Carrito de Compras donde un solo envío podrá contener productos de diferentes vendedores.
  • "cost": representa el costo final del envío que corresponde a cada usuario.

Lead Time

El recurso /shipments/shipment_id/lead_time devuelve todo lo referente a los plazos de entrega de un envío y tipo de servicio, sumando las fechas límites de despacho y entrega. Si bien el recurso base de shipment ya trae información útil para hacer estas estimaciones, acá podrás visualizarlo de manera más detallada, lo cual ayudará a dar una mejor experiencia para el usuario.
GET https://api.mercadolibre.com/shipments/shipment_id/lead_time
{
  "option_id": 0,
  "shipping_method": {
    "id": 0,
    "type": "standard",
    "name": "string",
    "deliver_to": "address"
  },
  "currency_id": "string",
  "cost": 0,
  "cost_type": "charged",
  "service_id": 0,
  "estimated_delivery_time": {
    "type": "known",
    "date": "string",
    "shipping": 0,
    "handling": 0,
    "unit": "string",
    "offset": {
      "date": "string",
      "shipping": 0
    },
    "time_frame": {
      "from": 0,
      "to": 0
    },
    "pay_before": "string"
  },
  "estimated_handling_limit": {
    "date":  "2016-12-30T12:32:35.000Z"
  },
  "estimated_delivery_extended": {
    "date":  "2016-12-30T12:32:35.000Z"
  },
  "estimated_delivery_limit": {
    "date":  "2016-12-30T12:32:35.000Z"
  },
  "estimated_delivery_final": {
    "date":  "2016-12-30T12:32:35.000Z"
  },
  "delay": [
    "shipping_delayed",
  ]
}
Nota: ten en en cuenta que el campo cost_type puede ser "free", "charged" o "partially_free".

Descripción de los tiempos de estimación

Son las fechas límite para que el envío sea despachado y enviado. estimated_handling_limit: Fecha límite que tiene el vendedor para despachar. Se considera que sólo se tiene en cuenta la fecha ya que la hora sólo se ingresa para mantener una estructura. Es decir, tienes el día completo que figura en el campo, para realizar el despacho antes de que el mismo se marque demorado al día siguiente. estimated_delivery_extended: Segunda promesa de entrega, en caso de que la original no se cumpla. estimated_delivery_limit: Fecha límite para que el comprador puede cancelar la compra y pedir la devolución de dinero, siempre y cuando todavía no haya llegado el envío. estimated_delivery_final: Fecha final como plazo para que llegue el envío y se determine el status final que puede ser delivered o, en caso de haber entrado un reclamo, not_delivered. Ver más información sobre los tipos de promesa de entrega.

History

El recurso /shipments/shipment_id/history devuelve el historial de status y substatus asociados al ciclo de vida del shipment.
GET https://api.mercadolibre.com/shipments/shipment_id/history

[
  {
    "status": "string",
    "substatus": "string",
    "date": "2016-12-30T12:32:35.000Z"
  }
]
Ejemplo:
https://api.mercadolibre.com/shipments/1234567899/history

[
  {
    "status": "ready_to_ship",
    "substatus": "printed",
    "date":  "2016-12-30T12:32:35.000Z"
  },
  {
    "status": "handling",
    "substatus": "waiting_for_label_generation",
    "date":  "2016-12-30T12:32:35.000Z"
  },

]
Ver información sobre los estado y subestado por los que puede pasar un envío.

Payments

El recurso /shipments/shipment_id/payments devuelve los payments asociados al envío. Ten en cuenta que ahora el pago del envío estará discriminado y vas a poder, desde este recurso, consumir información básica del mismo. El payment_id funciona de la misma manera que el correspondiente a una orden.
GET https://api.mercadolibre.com/shipments/shipment_id/payments
[
  {
    "payment_id": 0,
    "amount": 0,
    "status": "string"
  }
]

Parámetros disponibles

A continuación te mostraremos los valores disponibles para cada parámetro: logistic.direction: forward, return logistic.mode: me2, me1, custom logistic.type: default, drop_off, xd_drop_off, cross_docking, fulfillment
source.site_id: sites source.market_place: Mercado Libre, OFF
lead_time.shipping_method.type: next_day, express, standard, same_day lead_time.shipping_method.deliver_to: address, agency
lead_time.currency_id: currencies lead_time.cost_type: free, partially_free, charged
lead_time.delay: handling_delayed, shipping_delayed, shipping_delayed_extended
destination/origin.type: agency, buying_address, selling_address
discount.type: loyal, special

Items no combinables (nueva funcionalidad)

En caso que tengas un inconveniente al momento de agrupar diferentes productos en un mismo paquete (ya sea por que están en distintos depósitos, son frágiles, no entran en una misma caja, etc.) puedes utilizar el recurso que te permite generar paquetes adicionales para poder despachar todos los productos. Ejemplo:
POST https://api.mercadolibre.com/shipments/shipment_id/split?access_token=token
JSON:
	{
  "shipments": [
    {
      "reason": "text",
                   “description”: “text”
      "orders": [
        {
          "id": "order_id",

        }
      ]
    }
  ]
}
Ten en cuenta que este recurso es para evitar problemas a la hora de empaquetar pero no debe ser usada en todos los casos. Próximamente estaremos mejorando este proceso.

Valores posibles en el campo "reason"

  • fragile
  • another_warehouse
  • irregular_shape
  • other_motive
Notas:
  • El “order_ID” representa a la orden que contiene el producto que debe ser apartado del paquete original.
  • Se creará un nuevo shipment conteniendo la orden correspondiente al “order_ID” apartado.
  • La API no devolverá ninguna respuesta después de la llamada, solamente el status 201.
  • Una que se realiza el POST se creará un nuevo shipment lo cual disparará las notificaciones correspondientes.

Siguiente: Manejo de Pagos.

Forma parte de nuestra comunidad