Recursos para IA
Crear pago con envío
A través de la preferencia, es posible crear un pago con un envío asociado. De esta manera, podrás ofrecer a los clientes entregas a domicilio de los productos adquiridos aprovechando la logística de Mercado Libre y sin esfuerzos extra de parte del negocio.
La creación de envíos está disponible solo para integradores autorizados por Mercado Pago. Si aún no tienes habilitada esta funcionalidad, revisa su disponibilidad en tu cuenta de Mercado Pago.
Para crear un pago con un envío asociado, crea una preferencia enviando una solicitud al endpoint /checkout/preferencesPOST, incluyendo tu Access TokenClave privada de la aplicación creada en Mercado Pago, que es utilizada en el backend. Puedes acceder a ella a través de Tus integraciones > Datos de integración > Pruebas > Credenciales de prueba. El Access Token de prueba comienza con el prefijo `APP_USR`. y los nodos items y shipments como es indicado en la tabla a continuación.
curlcurl --location 'https://api.mercadopago.com/checkout/preferences' \ --header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \ --header 'Content-Type: application/json' \ --data '{ "external_reference": "Referencia externa 123", "items": [ { "title": "Producto 1", "description": "Descripción del producto 1", "picture_url": "image.jpg", "quantity": 1, "currency_id": "MXN", "unit_price": 100, "fiscal_data": { "sat": "23241500", "sat_measurement_id": "H87", "measurement_unit": "Pieza", "package_id": "4G", "dangerous_material_id": "M2340" }, "dimensions": { "unit": "G", "height": 3, "width": 11, "length": 18, "weight": 100 } }, { "title": "Producto 2", "description": "Descripción del producto 2", "picture_url": "image.jpg", "quantity": 1, "currency_id": "MXN", "unit_price": 110, "fiscal_data": { "sat": "23241500", "sat_measurement_id": "H87", "measurement_unit": "Pieza", "package_id": "4G", "dangerous_material_id": "M2340" }, "dimensions": { "unit": "G", "height": 3, "width": 10, "length": 18, "weight": 90 } }, ], "shipments": { "dimensions": "21x15x6.5,360", "free_methods_types": [ { "id": "standard" } ], "local_pickup": false, "mode": "me2", "stock_origin_id": "id", "receiver_address": { "zip_code": "06250", "street_name": "Ex-Hipódromo de Peralvillo", "street_number": null, "floor": "", "apartment": "", "neighborhood": Colonia, "city_name": Cuauhtémoc, "state_name": Ciudad de México, "country_name": México } } }'
| Campo | Descripción | Tipo | Obligatoriedad |
external_reference | Referencia que puedes sincronizar con tu sistema de pagos para identificar el envío. Este campo debe tener un máximo de 64 caracteres y solo debe contener números, letras, guiones (-) y guiones bajos (_). No se permiten caracteres especiales como ([ ], (), '', @). | String | Opcional |
items | Información sobre los ítems vendidos a ser enviados. | Array | Requerido |
items.title | Título del ítem que se mostrará durante el proceso de pago, en el checkout, actividades y correos electrónicos. | String | Requerido |
items.description | Descripción del ítem. | String | Opcional |
items.picture_url | URL de la imagen del ítem. | String | Opcional |
items.quantity | Cantidad de ítems. Esta propiedad se utiliza para calcular el costo total de la compra. | Number | Requerido |
items.currency_id | Identificador único de la moneda involucrada en la transacción. El único valor posible es pesos mexicanos (MXN). | String | Opcional |
items.unit_price | Precio unitario del ítem. Esta propiedad se usa junto con propiedad quantity para determinar el costo de la compra. | Number | Requerido |
items.fiscal_data | Objeto que contiene los datos fiscales del producto. | Object | Requerido para crear envíos. Si lo ingresas, debes incluir también el atributo shipments. |
items.fiscal_data.sat | Categoría SAT del ítem. Consulta los valores posibles accediendo al siguiente enlace. | String | Requerido |
items.fiscal_data.sat_measurement_id | Identificador único de la unidad de medida del producto. | String | Requerido |
items.fiscal_data.measurement_unit | Unidad de medida del producto de acuerdo con las SAT Units. | String | Requerido |
items.fiscal_data.package_id | Identificador del tipo de embalaje del producto. | String | Requerido |
items.fiscal_data.dangerous_material_id | Identificador para productos peligrosos. | String | Opcional |
items.dimensions | Objeto que contiene la información sobre el tamaño del ítem. | Object | Opcional |
items.dimensions.unit | Unidad de medida para el ítem. Debe ser cm (centímetros). | String | Requerido |
items.dimensions.height | Alto del ítem en centímetros. | Number | Requerido |
items.dimensions.width | Ancho del ítem en centímetros. | Number | Requerido |
items.dimensions.length | Largo del ítem en centímetros. | Number | Requerido |
items.dimensions.weight | Peso del ítem en gramos. | Number | Requerido |
shipments | Información del envío. | Object | Obligatorio |
shipments.dimensions | Tamaño del paquete, que se utilizará para definir el costo del envío. El formato debe ser cm x cm x cm, g. Si contiene más de un ítem, su tamaño debe calcularse considerando la suma de las dimensiones de todos los artículos, asegurando siempre que no se superen las dimensiones máximas permitidas por paquete.Consulta las buenas prácticas para el dimensionamiento accediendo a la documentación. | String | Requerido |
shipments.free_methods_type | Identificador de método de envío. Solo debe enviarse en caso de ofrecer envío gratuito, con el valor standard. Este envío gratuito solo es posible cuando el valor de la venta es mayor que el costo de envío. En caso de que el costo del envío esté a cargo del comprador, el campo no debe enviarse. | String | Opcional |
shipments.local_pickup | Indica si se quiere ofrecer recolección de paquetes en sucursal. Para esta solución, ingresa false. | Boolean | Requerido |
shipments.mode | Modo de envío. Para esta solución, ingresa me2. | String | Requerido |
shipments.stock_origin_id | Identificador de la dirección de origen del paquete, que debe ser solicitado al equipo de Mercado Pago. En caso de haber más de una dirección de recolección, deberá ser informado el stock_origin_id de la dirección de origen. | String | Opcional |
shipments.receiver_address | Detalles de la dirección de destino. Su envío es recomendado para ofrecer la mejor experiencia de compra y, de ser necesario, los datos pueden ser reutilizados. | Object | Opcional |
shipments.receiver_address.zip_code | Código postal de la dirección de destino. | String | Opcional |
shipments.receiver_address.street_name | Nombre de la calle de destino. | String | Opcional |
shipments.receiver_address.street_number | Número de la dirección de destino. | String | Opcional |
shipments.receiver_address.floor | Piso del apartamento de destino. | String | Opcional |
shipments.receiver_address.apartment | Número del apartamento de destino. | String | Opcional |
shipments.receiver_address.neighborhood | Barrio de la dirección de destino. | String | Opcional |
shipments.receiver_address.city_name | Ciudad de la dirección de destino. | String | Opcional |
shipments.receiver_address.state_name | Estado de la dirección de destino. | String | Opcional |
shipments.receiver_address.country_name | País de la dirección de destino. | String | Opcional |
Si la solicitud se envió correctamente, el pago con envío habrá sido creado y la respuesta se verá como en el ejemplo a continuación.
json{ "additional_info": "", "auto_return": "", "back_urls": { "failure": "", "pending": "", "success": "" }, "binary_mode": false, "client_id": "6607075136335166", "collector_id": 2681149695, "coupon_code": null, "coupon_labels": null, "date_created": "2025-10-15T15:30:39.775-04:00", "date_of_expiration": null, "expiration_date_from": null, "expiration_date_to": null, "expires": false, "external_reference": "Referencia externa 123", "id": "2681149695-c464c4e0-1834-4e81-9956-25a3cc1e8db8", "init_point": "https://www.mercadopago.com.mx/checkout/v1/redirect?pref_id=2681149695-c464c4e0-1834-4e81-9956-25a3cc1e8db8", "internal_metadata": null, "items": [ { "id": "", "category_id": "", "currency_id": "MXN", "description": "Descripción del producto 1", "title": "Producto 1", "quantity": 1, "unit_price": 100, "fiscal_data": { "sat": "23241500", "sat_measurement_id": "H87", "measurement_unit": "Pieza", "package_id": "4G", "dangerous_material_id": "M2340" }, "dimensions": { "unit": "G", "height": 3, "width": 11, "length": 18, "weight": 100 } }, { "id": "", "category_id": "", "currency_id": "MXN", "description": "Descripción del producto 2", "title": "Producto 2", "quantity": 1, "unit_price": 110, "fiscal_data": { "sat": "23241500", "sat_measurement_id": "H87", "measurement_unit": "Pieza", "package_id": "4G", "dangerous_material_id": "M2340" }, "dimensions": { "unit": "G", "height": 3, "width": 10, "length": 18, "weight": 90 } }, ], "marketplace": "NONE", "marketplace_fee": 0, "metadata": {}, "notification_url": null, "operation_type": "regular_payment", "payer": { "phone": { "area_code": "", "number": "" }, "address": { "zip_code": "", "street_name": "", "street_number": null }, "email": "", "identification": { "number": "", "type": "" }, "name": "", "surname": "", "date_created": null, "last_purchase": null }, "payment_methods": { "default_card_id": null, "default_payment_method_id": null, "excluded_payment_methods": [ { "id": "" } ], "excluded_payment_types": [ { "id": "" } ], "installments": null, "default_installments": null }, "processing_modes": null, "product_id": null, "preference_expired": false, "redirect_urls": { "failure": "", "pending": "", "success": "" }, "sandbox_init_point": "https://sandbox.mercadopago.com.mx/checkout/v1/redirect?pref_id=2681149695-c464c4e0-1834-4e81-9956-25a3cc1e8db8", "site_id": "MLM", "shipments": { "mode": "me2", "local_pickup": false, "dimensions": "21x15x6.5,360", "free_methods": [], "free_methods_types": [ { "id": "standard" } ], "default_shipping_method": null, "receiver_address": { "zip_code": "06250", "street_name": "Ex-Hipódromo de Peralvillo", "street_number": null, "floor": "", "apartment": "", "city_name": "Cuauhtémoc", "state_name": "Ciudad", "country_name": "México", "neighborhood": "Colonia" }, "stock_origin_id": "id" }, "total_amount": null, "last_updated": null, "financing_group": "" }
El campo
sandbox_init_point aparece en la respuesta, pero no es funcional. Para pruebas de integración, debes utilizar init_point.En caso de ser necesario, puedes cancelar el envío creado. Para eso, cancela en su totalidad el pago al que está asociado mediante el endpoint /v1/payments/{id}PUT.
Si eliges crear pagos con envíos, puedes utilizar nuestras APIs de gestión de envíos, que te permitirán optimizar tu experiencia pre y posventa.
Para cotizar un envío, envía una solicitud al endpoint /shipping/v1/shipments-ratesPOST incluyendo tu Access TokenClave privada de la aplicación creada en Mercado Pago, que es utilizada en el backend. Puedes acceder a ella a través de Tus integraciones > Datos de integración > Pruebas > Credenciales de prueba. El Access Token de prueba comienza con el prefijo `APP_USR`. y los parámetros descritos en la tabla a continuación. Ten en cuenta que solo es posible cotizar el envío de un paquete por vez.
curlcurl --location 'https://api.mercadopago.com/shipping/v1/shipments-rates' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \ --data '{ "packages": [ { "declared_value": 1500, "quantity": 1, "dimensions": { "weight": 500, "width": 30, "height": 30, "length": 30 } } ], "shipping_from": { "zip_code": "06760" }, "shipping_to": { "zip_code": "06720" } }'
| Campo | Descripción | Tipo | Obligatoriedad |
packages | Contiene la información del paquete para la cotización. | Array | Requerido |
packages.declared_value | Valor del paquete a ser enviado. No incluye el costo estimado de envío. | Number | Requerido |
packages.quantity | Cantidad de paquetes. El único valor permitido es 1. | Number | Requerido |
packages.dimensions | Objeto que contiene las dimensiones del paquete. Los máximos permitidos son: - Cada lado debe tener un máximo de 150 cm. - El límite de dimensiones totales no debe superar los 330 cm. - El peso máximo es de 30 kg (real o volumétrico). | Object | Requerido |
packages.dimensions.height | Alto del paquete en centímetros. | Number | Requerido |
packages.dimensions.width | Ancho del paquete en centímetros. | Number | Requerido |
packages.dimensions.length | Largo del paquete en centímetros. | Number | Requerido |
packages.dimensions.weight | Peso del paquete en gramos. | Number | Requerido |
shipping_from.zip_code | Código postal de la dirección de origen. Si se informa este valor, se usará para calcular la oferta. De lo contrario, se aplicará el dato de Envíos configurado en Mercado Pago. | String | Opcional |
shipping_to.zip_code | Código postal de la dirección de destino. | String | Requerido |
Si la solicitud es correcta, la respuesta devolverá la cotización del envío, que puede contener más de una opción variables en precio y/o plazo.
json{ "shipment_rate_id": "be9fae0d-1079-471e-887d-55861965d10e", "rates": [ { "options": [ { "id": "3c86ea36-fef7-4a9e-9092-d4eb6e744834", "pricing": { "base_price": "87", "price": "87", "discounts": [] }, "method": "standard", "pay_before": "2025-10-27T00:00:00-06:00", "delivery_promise": { "shipping_from": "2025-10-28T12:00:00-06:00", "shipping_to": "2025-10-30T12:00:00-06:00" }, "delivery_days": { "from": 3, "to": 5 } } ], "packages": [ { "quantity": 1, "dimensions": { "weight": "500", "width": "30", "height": "30", "length": "30" } } ] } ], "shipping_to": { "zip_code": "06720", "country_id": "MX", "city_id": "TUxNQ0NVQTczMTI", "state_id": "MX-DIF" } }
| Campo | Descripción | Tipo |
shipment_rate_id | Identificador de la cotización. Usa este valor como shipment_rate_id al crear el envío. | String |
rates | Lista de cotizaciones para el paquete en función de la dirección informada. | Array |
options | Lista de las opciones de cotizaciones disponibles. | Array |
id | Identificador de la opción de envío. Usa este valor como option_id al crear el envío a partir de la cotización. | String |
base_price | Valor bruto del envío. | Number |
price | Valor neto del envío. | Number |
method | Método de entrega. La única respuesta posible a este campo es standard, para envíos gratuitos. | String |
pay_before | Expectativa de fecha del pago para asegurar la promesa de envío generada. | Date |
delivery_promise.shipping_from | Fecha inicial de la promesa de entrega. | String |
delivery_promise.shipping_to | Fecha final de la promesa de entrega. | String |
delivery_days.from | Mínimo de días hábiles para la promesa de entrega. | Integer |
delivery_days.to | Máximo de días hábiles para la promesa de entrega. | Integer |
packages.quantity | Cantidad de paquetes cotizados. | Number |
packages.dimensions | Dimensiones del paquete cotizado. | Object |
packages.dimensions.height | Alto del paquete. | Number |
packages.dimensions.width | Ancho del paquete. | Number |
packages.dimensions.length | Largo del paquete. | Number |
packages.dimensions.weight | Peso del paquete. | Number |
shipping_to.zip_code | Código postal del domicilio de destino. | String |
shipping_to.city_id | Identificador de la ciudad de la dirección de destino. | String |
shipping_to.state_id | Sigla del estado de la dirección de destino. | String |
shipping_to.country_id | Sigla del país de la dirección de destino. | String |
Para conocer los errores que puede devolver esta solicitud, dirígete a nuestra Referencia de APIAPI.
Configura notificaciones Webhooks para recibir alertas sobre envíos y sus cambios de estado.
Para hacerlo, es necesario indicar las URLs a las que las mismas serán enviadas siguiendo el paso a paso a continuación:
- Ingresa a Tus integraciones y selecciona la aplicación integrada con Checkout Pro para la que deseas activar las notificaciones.
- En el menú de la izquierda, selecciona Webhooks > Configurar notificaciones.
- Selecciona la pestaña Modo productivo y proporciona una
URL HTTPSpara recibir notificaciones con tu integración productiva.
- Selecciona el evento Envíos (Mercado Pago) para recibir notificaciones, que serán enviadas en formato
JSONa través de unHTTPS POSTa la URL especificada anteriormente.
- Por último, haz clic en Guardar configuración. Esto generará una clave secreta exclusiva para la aplicación, que permitirá validar la autenticidad de las notificaciones recibidas, garantizando que hayan sido enviadas por Mercado Pago. Ten en cuenta que esta clave generada no tiene plazo de caducidad y su renovación periódica no es obligatoria, aunque sí recomendada. Para hacerlo, basta con cliquear en el botón Restablecer.
Si deseas obtener más información sobre cómo simular el envío de una notificación, validar su origen, o cuáles son las acciones necesarias luego de recibirlas, dirígete a Configurar notificaciones.