Gestionar envíos

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

Contenidos

→Consultar envíos
→Ítems asociados a un envío
→Costos del envío
    ↳Parámetros
→Pagos de un envío
→Plazos de entrega (Handling time)
→Campos de respuesta (tiempos estimados)
→Consultar envíos con retraso
→Consultar historial (status y substatus) del envío
→Status y substatus front vs. API
→Consultar información del transporte (carrier)
→Información sobre estados y subestados de un envío
→Ítems no combinables
   


Es importante recordar que el nuevo JSON de Orders ya no contendrá datos de Shipping, como ha sido hasta ahora. El recurso /shipments/shipment_id/ seguirá teniendo su estructura, mostrando la información básica para realizar el envío. Hemos introducido algunos cambios en la estructura JSON, que puede ver a continuación


Consultar envíos

Nota:
Puedes acceder a la información de los diferentes tipos de logísticas desde Mercado Envíos 2.
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipments/$SHIPMENT_ID
{
  "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"
  ]
}

Consulta cada uno de los parámetros:

curl -X OPTION -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipments/$SHIPMENT_ID
Nota:
external_reference hace referencia al número de pack relacionado con el envío.


Ítems asociados a un envío

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.
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 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
  }
]


Costos del envío

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".
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipments/$SHIPMENT_ID/costs
{
	"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.


Pagos de un envío

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.

Llamada:

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

Ejemplo:

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

Respuesta:

[
   {
       "payment_id": 1111111111,
       "user_id": 291760105,
       "amount": 17.7,
       "status": "approved"
   }
]


Plazos de entrega (Handling 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.

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 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",
  ]
}

El campo cost_type puede ser "free", "charged" o "partially_free".


Campos de respuesta (tiempos estimados)

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 costos de envío y handling time.


Consultar envíos con retraso

Importante:
Los vendedores deberán despachar sus paquetes teniendo en cuenta un horario indicado para evitar afectar su reputación. Consulta el horario máximo según el tipo de logística de la cuenta:
- Argentina: a partir del 5 de julio de 2021
- Brasil y México: a partir del 12 de julio de 2021
- Chile y Uruguay: a partir del 19 de julio de 2021
- Colombia: a partir del 29 de julio de 2021

Para conocer los envíos con retraso, utiliza el recurso /delays:

Llamada:

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

Ejemplo:

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

Respuesta:

{
	"shipment_id": 30143583389,
	"delays": [{
		"type": "handling_delayed",
		"date": "2020-09-23T09:07:20Z",
		"source": "shipping-delays"
	}]
}
Notas:
- El type sla_delayed indica que superó el tiempo esperado de despacho definido por el SLA.
- Cuando el envío no tiene retraso, recibirás error 404: "Delays Not Found for shipment".

Próximamente disponibilizaremos un recurso para consultar los horarios y automatizar el proceso.


Consultar historial (status y substatus) del envío

Ejemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 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"
   }
]
Nota:
Ventas donde el pago falló, pueden tener el medio de envío original cambiado, ya que hay una recompra. Para casos donde la compra original tenia un envío asociado, y la recompra un "to be agree", el status del envío si quedará status: "cancelled", y substatus: "closed_by_user", y la venta necesita ser cancelada


Status y substatus Front vs. API

Ten en cuenta que los substatus pueden cambiar en base a los tipos logísticos.


Tracking para Cross Docking

Front Descripción API - "status_history"
"En preparación" "Estamos preparando el paquete" status: handling
"En camino" "El vendedor despachó ty paquete" status: ready_to_ship
substatus: picked_up, authorized_by_carrier
"Ingresó al centro de distribución de ....." status: ready_to_ship
substatus: in_hub
"Entregado" "Entregamos el paquete" status: delivered

Tracking para Fulfillment

Front Descripción API - "status_history"
"En preparación" "Estamos preparando el paquete" status: handling
"En camino" "El paquete salió del centro de distribuición" status: shipped
"Entregado" "Entregamos el paquete" status: delivered

Consultar información del transporte (carrier)

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipments/$SHIPMENT_ID/carrier
{
   "url":"string",
   "name":"string"
}

Ejemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipments/27691621451/carrier
{
   "url":"http://tracking.totalexpress.com.br/poupup_track.php?reid=3&pedido=14&nfiscal=1", 
   "name":"Total Express"
}

Información sobre estados y subestados de un envío

Llamada:

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

Respuesta:

{
    "id": "to_be_agreed",
    "name": "To be agreed",
    "substatuses": [
    ]
  },
  {
    "id": "pending",
    "name": "Pending",
    "substatuses": [
      {
        "id": "cost_exceeded",
        "name": "Cost exceeded"
      }
    ]
  },
  {
    "id": "handling",
    "name": "Handling",
    "substatuses": [
      {
        "id": "regenerating",
        "name": "Regenerating"
      },
      {
        "id": "waiting_for_label_generation",
        "name": "Waiting for label generation"
      }
    ]
  },
  {
    "id": "ready_to_ship",
    "name": "Ready to ship",
    "substatuses": [
      {
        "id": "ready_to_print",
        "name": "Ready to print"
      },
      {
        "id": "invoice_pending",
        "name": "Invoice pending"
      },
      {
        "id": "printed",
        "name": "Printed"
      },
      {
        "id": "in_pickup_list",
        "name": "In pikcup list"
      },
      {
        "id": "ready_for_pkl_creation",
        "name": "Ready for pkl creation"
      },
      {
        "id": "ready_for_pickup",
        "name": "Ready for pickup"
      },
      {
        "id": "picked_up",
        "name": "Picked up"
      },
      {
        "id": "stale",
        "name": "Stale Ready To Ship"
      },
      {
        "id": "in_hub",
        "name": "In hub"
      },
      {
        "id": "measures_ready",
        "name": "Measures and weight ready"
      },
      {
        "id": "waiting_for_carrier_authorization",
        "name": "Waiting for carrier authorization"
      },
      {
        "id": "authorized_by_carrier",
        "name": "Authorized by carrier"
      },
      {
        "id": "in_plp",
        "name": "In PLP"
      }
    ]
  },
  {
    "id": "shipped",
    "name": "Shipped",
    "substatuses": [
      {
        "id": "delayed",
        "name": "Delayed"
      },
      {
        "id": "waiting_for_withdrawal",
        "name": "Waiting for withdrawal"
      },
      {
        "id": "contact_with_carrier_required",
        "name": "Contact with carrier required"
      },
      {
        "id": "receiver_absent",
        "name": "Receiver absent"
      },
      {
        "id": "reclaimed",
        "name": "Reclaimed"
      },
      {
        "id": "not_localized",
        "name": "Not localized"
      },
      {
        "id": "forwarded_to_third",
        "name": "Forwarded to third party"
      },
      {
        "id": "soon_deliver",
        "name": "Soon deliver"
      },
      {
        "id": "refused_delivery",
        "name": "Delivery refused"
      },
      {
        "id": "bad_address",
        "name": "Bad address"
      },
      {
        "id": "negative_feedback",
        "name": "Stale shipped with negative feedback by buyer"
      },
      {
        "id": "need_review",
        "name": "Need to review carrier status to understand what happened"
      },
      {
        "id": "stale",
        "name": "Stale shipped"
      }
    ]
  },
  {
    "id": "delivered",
    "name": "Delivered",
    "substatuses": [
      {
        "id": "damaged",
        "name": "damaged"
      },
      {
        "id": "fulfilled_feedback",
        "name": "Fulfilled by buyer feedback"
      },
      {
        "id": "no_action_taken",
        "name": "No action taken by buyer"
      },
      {
        "id": "double_refund",
        "name": "Double Refund"
      }
    ]
  },
  {
    "id": "not_delivered",
    "name": "Not delivered",
    "substatuses": [
      {
        "id": "returning_to_sender",
        "name": "Returning to sender"
      },
      {
        "id": "retained",
        "name": "Retained"
      },
      {
        "id": "stolen",
        "name": "Stolen"
      },
      {
        "id": "returned",
        "name": "Returned"
      },
      {
        "id": "receiver_absent",
        "name": "Receiver absent"
      },
      {
        "id": "confiscated",
        "name": "confiscated"
      },
      {
        "id": "to_review",
        "name": "Closed shipment"
      },
      {
        "id": "destroyed",
        "name": "Destroyed"
      },
      {
        "id": "waiting_for_withdrawal",
        "name": "Waiting for withdrawal"
      },
      {
        "id": "negative_feedback",
        "name": "Stale shipped forced to not delivered due to negative feedback by buyer"
      },
      {
        "id": "claimed_me",
        "name": "Stale shipped with claim that was forced to not delivered"
      },
      {
        "id": "not_localized",
        "name": "Not localized"
      },
      {
        "id": "double_refund",
        "name": "Double Refund"
      }
    ]
  },
  {
    "id": "not_verified",
    "name": "Not verified",
    "substatuses": [
    ]
  },
  {
    "id": "cancelled",
    "name": "Cancelled",
    "substatuses": [
    ]
  },
  {
    "id": "closed",
    "name": "Closed",
    "substatuses": [
    ]
  },
  {
    "id": "error",
    "name": "Error",
    "substatuses": [
    ]
  },
  {
    "id": "active",
    "name": "Active",
    "substatuses": [
    ]
  },
  {
    "id": "not_specified",
    "name": "Not specified",
    "substatuses": [
    ]
  },
  {
    "id": "stale_ready_to_ship",
    "name": "Stale ready to ship",
    "substatuses": [
    ]
  },
  {
    "id": "stale_shipped",
    "name": "Stale shipped",
    "substatuses": [
    ]
  }


Ítems no combinables

Importante:
Este recurso no aplica a ventas con Envíos Flex.

En caso que tengas un inconveniente al momento de agrupar diferentes productos en un mismo paquete (ya sea porque 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.

Llamada:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -d
{
  "shipments": [
    {
      "reason": "text",
                   "description": "text"
      "orders": [
        {
          "id": "order_id",

        }
      ]
    }
  ]
}
https://api.mercadolibre.com/shipments/$SHIPMENT_ID/split


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.

Conoce más sobre Modos de Envíos.


Siguiente: Gestionar pagos.

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