Gestiona reservas
Contenidos
→Beneficios →Recibe una orden →Búsqueda de órdenes →Órdenes Recientes →Órdenes Archivadas →Órdenes Pendientes →Estado de la orden →Flujo de Mercado Pago obligatorio (sólo para países con MP) →¿Cómo tu app toma conocimiento de una compra? →Recibir una notificación →Recibir o enviar mensajes →Pagos →Escenario de pagos múltiples →¿Cómo puedo saber si existen dos pagos? →¿Cómo obtener información de un pago? →¿Cómo obtener información del pago siendo vendedor? →Notas de órdenes →¿Cómo agregar una nota a una orden? →Visualiza notas de órdenes →¿Cómo modificar una nota? →Elimina notas →Bloquea ofertas →¿Cómo bloqueo ofertas de un usuario específico? →Consulta tu lista negra →Elimina a un usuario de tu lista negra →Entregar o devolver reserva
Beneficios
- Mejora posicionamiento: Por cada reserva exitosa, las reservas estarán mejor posicionadas en el listado.
- El vendedor contará con reputación: Si brinda una buena experiencia se diferenciará de los competidores.
- No tiene costos adicionales.
Conoce más detalles de reservas online de vehículos.
Recibe una orden
Una vez que se crea una nueva orden en el usuario, se puede consultar los detalles al realizar una solicitud al recurso de órdenes:
Ejemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/$ORDER_ID
Respuesta:
{
"id":768570754,
"status":"paid",
"status_detail":null,
"date_created":"2013-05-27T10:01:50.000-04:00",
"date_closed":"2013-05-27T10:04:07.000-04:00",
"order_items":[
{
"item":{
"id":"MLB12345678",
"title":"Nissan March MARCH 1.0 S 12V FLEX 4P MANUAL",
"category_id":"MLB1234",
"variation_id":null,
"variation_attributes":[
]
},
"quantity":1,
"unit_price":499,
"full_unit_price":25000,
"currency_id":"BRL"
}
],
"total_amount":499,
"currency_id":"BRL",
"buyer":{
"id":"123456789",
"nickname":"COMPRADORTESTE",
"email":"b@b.com",
"phone":{
"area_code":"11",
"number":"12345678",
"extension":null
},
"first_name":"Comprador de testes",
"last_name":"da Silva",
"billing_info":{
"doc_type":"CPF",
"doc_number":"12345678910"
}
},
"seller":{
"id":"123456789",
"nickname":"VENDEDORTESTES",
"email":"a@a.com",
"phone":{
"area_code":null,
"number":"11 12345678",
"extension":"11"
},
"first_name":"Vendedor de Testes",
"last_name":"testes de documentacao"
},
"payments":[
{
"id":"596707837",
"transaction_amount":499,
"currency_id":"BRL",
"status":"approved",
"date_created":null,
"date_last_modified":null
}
],
"feedback":{
"purchase":null,
"sale":null
},
"shipping":{
"status":"to_be_agreed"
},
"tags":[
"reservation",
"paid",
"not_delivered"
]
}
Existen gran cantidad de atributos conforme a una orden. A continuación veremos una descripción de los campos más importantes.
id Identificador único de la orden.
date_created Fecha de creación de la orden
date_closed Fecha de confirmación de la orden. Se define cuando una orden cambia por primera vez al estado: confirmed / paid y se descuenta el stock del ítem.
expiration_date Fecha límite que tiene el usuario para calificar porque, luego de la misma, se vuelve visible el feedback, se emiten los pagos (si hubiese) y se crean los cargos.
status Estado de la orden.
status_detail Detalle del estado, en caso de cancelación de la orden.
code Código del estado.
description Descripción del estado.
comprador Información del comprador.
vendedor Información del vendedor.
order_items Publicaciones en la orden.
unit_price Precio de la reserva.
full_unit_price Precio total del item.
payments Pagos relacionados con la orden.
feedback Información de feedback relacionada con la orden.
total_amount Monto total de la orden.
currency_id ID de moneda.
tags Lista de los tags seleccionados por el vendedor, tales como entregado, pagado, además del tag “reservation” que marca la orden como reserva.
Búsqueda de órdenes
El recurso de búsqueda de órdenes te ayudará a buscar cada orden que pertenece a usuarios para quienes tienen un token válido.
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/search?buyer=$BUYER_ID
Dentro del seach a orders están disponibles los campos “available_filters” y “available_sorts”. Ten en cuenta que el search no muestra aquellas órdenes en estado Payment_required.
¿Cómo filtrar?
Para filtrar tus órdenes con status “paid” encontrarás entre los “available_filters” disponibles el ID “order.status” y dentro de éste el value con ID “paid”.
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/search?seller=$SELLER_ID&order.status=paid
En el caso de querer filtrar tus órdenes por fecha deberás hacerlo de la siguiente manera:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/search?seller=&order.date_created.from=2015-07-01T00:00:00.000-00:00&order.date_created.to=2015-07-31T00:00:00.000-00:00
¿Cómo ordenar?
En este caso deberás agregar “sort” con el ID disponible del orden que quieras aplicar, por ejemplo: “date_desc”curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/search?seller=$SELLER_ID&order.status=paid&sort=date_desc
Órdenes recientes
Las órdenes recientes son las más nuevas generadas para un usuario. La respuesta incluirá órdenes en los que la fecha actual es anterior a la expiration_date y aún no has marcado como entregado el vehículo.
Búsqueda de las órdenes recientes de un vendedor:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/search/recent?seller=$SELLER_ID
Búsqueda de las órdenes recientes de un comprador:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/search/recent?buyer=$BUYER_ID
Órdenes archivadas
Si buscas una orden con expiration_date posterior a la fecha actual o que fue calificada por ambas partes, puedes utilizar el recurso de búsqueda en órdenes archivadas:
Búsqueda de las órdenes archivadas de un vendedor:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/search/archived?seller=$SELLER_ID
Búsqueda de las órdenes archivadas de un comprador:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/search/archived?buyer=$BUYER_ID
Órdenes pendientes
Esta búsqueda recuperará todas las órdenes en estado “pendiente” y omitirá las canceladas automáticamente. Si deseas ver las órdenes de un vendedor, envía el seller_id:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/search/pending?seller=$SELLER_ID
Para buscar por comprador, reemplaza los parámetros como se indica a continuación:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/search/pending?buyer=$USER_ID
Estado de la orden
Los estados de la orden son los siguientes:
payment_required: es necesario que se confirme el pago de la orden necesita para mostrar la información del usuario.
payment_in_process: existe un pago relacionado con la orden, pero aún no se acreditó.
partially_paid: la orden tiene un pago asociado acreditado, pero no es suficiente.
paid: la orden tiene un pago asociado acreditado.
cancelled: por alguna razón, la orden no se completó.*
Flujo de Mercado Pago obligatorio (sólo para países con MP)
¿Cómo saber si un site tiene Mercado Pago activo?
Para obtener esa información deberás realizar la siguiente llamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/sites/MLA
Si obtienes “MLAMP” como respuesta dentro de los “payment_method_ids” podrás trabajar sin problemas con este flujo. Aclaración: MLAMP es el ID del método de pago Mercado Pago:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/payment_methods/MLAMP
Dentro de nuestra plataforma encontrarás orders que pueden entrar por el flujo obligatorio de Mercado Pago como único medio de pago y otras que no.
Los escenarios que se presentan a continuación son en los que podrás encontrar esta opción de manera obligatoria:
- Todas las órdenes de MLB.
- Todas las órdenes de MLA y MLM por venta de productos con “condition”: “new”.
- Publicaciones de Tiendas Oficiales en todos los países con Mercado Pago.
- Categorías con Mercado Pago como única opción.
- Usuario marcado automáticamente para que sus operaciones vayan por este flujo, con la marca “immediate_payment” en la API de users.
- Vendedor “auto” marcado para que sus ventas vayan por este flujo.
Ahora explicamos cómo es el funcionamiento general de las órdenes ya sea que ingresen por este flujo o no:
1) Las órdenes que entran por este flujo se crean en estado “payment_required”. En ese momento tienen las siguientes características:
- No son visibles para el seller.
- No se descuenta el stock de item.
- No tienen establecido el campo date_closed.
- No tienen datos de la contraparte.
- Se envía sólo la notificación del topic “created_orders”.
2) Cuando el pago se acredita por el monto de la reserva, que es distinto del monto total del item, la orden pasa del estado “payment_required” a “paid”. En ese momento:
- Se hacen visibles para el seller.
- Se establece el campo date_closed.
- Se agregan los datos de la contraparte.
- Comienzan a enviarse además las notificaciones del topic “orders”.
¿Cómo tu app toma conocimiento de una compra?
La creación de una orden es un evento que se produce del lado de Mercado Libre, por eso deberás suscribirte a nuestro feed de orders para tomar conocimiento en tiempo real cuando ese evento ocurre. Dirígete a nuestro Administrador de Aplicaciones y edita las Configuraciones de Notificaciones de tu aplicación. Para más información, puedes consultar cómo crear y configurar una nueva aplicación.
Debes seleccionar un Callback URL: configura el URL público del dominio donde deseas recibir todas las notificaciones de Mercado Libre. Por ejemplo: “https://backend.soleorigami.com/notification”.

Esta configuración te permite interactuar con las notificaciones de Mercado Libre. Todos los eventos (como pagos y envío) relacionados con un orden serán notificados a tu callback URL.
Recibir una notificación
Mercado Libre te enviará notificaciones a través de un mensaje POST con información en el cuerpo de publicación. El atributo más importante del mensaje es el user_id, que está relacionado con la notificación, y el segundo en importancia es el recurso. El recurso es el elemento que fue actualizado o creado.
{
"user_id": 1234,
"resource": "/orders/731867397",
"topic": "orders",
"received": "2011-10-19T16:38:34.425Z",
"application_id" : 14529
"sent" : "2011-10-19T16:40:34.425Z",
"attempts" : 0
}
Después de recibir la notificación, debes enviar un acuse de recibo [acknowledgment] (ACK 200) a Mercado Libre para dejar de recibirla.
Recibir o enviar mensajes
Para trabajar con mensajería post venta te sugerimos leer nuestra documentación.
Pagos
Mercado Pago es la plataforma de pagos de Mercado Libre. Si deseas integrar una solución de pagos en tu plataforma, debes consultar el sitio de desarrolladores de Mercado Pago.
Escenario de pagos múltiples
En algunos casos, cuando se rechaza el pago por llegar al límite de la tarjeta de crédito, permitimos a los usuarios agregar otro pago con una segunda tarjeta de crédito.
¿Cómo puedo saber si existen dos pagos?
Cuando realizas una solicitud GET a la API de órdenes, verás que dentro del conjunto de pagos habrá dos ID con los detalles de cada pago.
Ejemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/893431118
Respuesta:
{
"buyer":{
"alternative_phone":{
"area_code":null,
"extension":null,
"number":""
},
"billing_info":{
"doc_number":"67045427794",
"doc_type":"CPF"
},
"email":"test_user_21963158@testuser.com",
"first_name":"Test",
"id":160903317,
"last_name":"Test",
"nickname":"TETE2022123",
"phone":{
"area_code":"01",
"extension":null,
"number":"1111-1111"
}
},
"coupon":{
"amount":0,
"id":null
},
"currency_id":"BRL",
"date_closed":null,
"date_created":"2014-10-26T22:46:18.000-04:00",
"feedback":{
"purchase":null,
"sale":null
},
"id":893431118,
"last_updated":"2014-10-26T22:50:10.000-04:00",
"mediations":[
],
"order_items":[
{
"currency_id":"BRL",
"item":{
"id":"MLB600034093",
"title":"Item De Testeo, Por Favor No Ofertar --kc:off",
"category_id":"MLB1234",
"variation_attributes":[
],
"variation_id":null
},
"quantity":1,
"unit_price":591,
"full_unit_price":25000
}
],
"paid_amount":591,
"payments":[
{
"activation_uri":null,
"atm_transfer_reference":{
"company_id":null,
"transaction_id":null
},
"available_actions":[
],
"card_id":null,
"collector":{
"id":169648308
},
"coupon_amount":0,
"coupon_id":null,
"currency_id":"BRL",
"date_created":"2014-10-26T22:48:46.000-04:00",
"date_last_modified":"2014-10-27T00:51:53.000-04:00",
"id":885920310,
"installments":1,
"issuer_id":"25",
"operation_type":"regular_payment",
"order_id":893431118,
"overpaid_amount":0,
"payer_id":160903317,
"payment_method_id":"visa",
"payment_type":"credit_card",
"reason":"Item De Testeo, Por Favor No Ofertar --kc:off",
"shipping_cost":0,
"site_id":"MLB",
"status":"approved",
"status_code":null,
"status_detail":"accredited",
"total_paid_amount":296,
"transaction_amount":296
},
{
"activation_uri":null,
"atm_transfer_reference":{
"company_id":null,
"transaction_id":null
},
"available_actions":[
],
"card_id":null,
"collector":{
"id":169648308
},
"coupon_amount":0,
"coupon_id":null,
"currency_id":"BRL",
"date_created":"2014-10-26T22:50:10.000-04:00",
"date_last_modified":"2014-10-26T22:50:21.000-04:00",
"id":885920410,
"installments":3,
"issuer_id":"25",
"operation_type":"regular_payment",
"order_id":893431118,
"overpaid_amount":0,
"payer_id":160903317,
"payment_method_id":"visa",
"payment_type":"credit_card",
"reason":"Item De Testeo, Por Favor No Ofertar --kc:off",
"shipping_cost":0,
"site_id":"MLB",
"status":"approved",
"status_code":null,
"status_detail":"accredited",
"total_paid_amount":315.62,
"transaction_amount":295
}
],
"seller":{
"alternative_phone":{
"area_code":null,
"extension":null,
"number":""
},
"email":"test_user_70385259@testuser.com",
"first_name":"Test",
"id":169648308,
"last_name":"Test",
"nickname":"TETE6072468",
"phone":{
"area_code":"01",
"extension":null,
"number":"1111-1111"
}
},
"shipping":{
"status":"to_be_agreed"
},
"status":"paid",
"status_detail":null,
"tags":[
"not_delivered",
"paid"
],
"total_amount":591,
"total_amount_with_shipping":591
}
¿Cómo obtener información de un pago?
Para obtener información del pago de un comprador utilizando el token deberás recurrir al recurso “payments”.
Ejemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/payments
¿Cómo obtener información del pago siendo vendedor?
Para obtener información del pago desde el rol del vendedor, el recurso que deberás acudir con el payment_id es “collections”.
Ejemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/collections/$COLLECTION_ID
Notas de órdenes
Una nota es una anotación que los vendedores pueden agregar a las órdenes. Las notas pueden tener hasta 300 caracteres cada una y, una vez que publicas una nota, puedes modificarla o eliminarla.
¿Cómo agregar una nota a una orden?
curl -X POST -H 'Content-Type: application/json' -H 'Authorization: Bearer $ACCESS_TOKEN' -d '{
"note": "test",
}'
https://api.mercadolibre.com/orders/$ORDER_ID/notes
Visualiza notas de órdenes
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/$ORDER_ID/notes
Cómo modificar una nota
curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'Content-Type: application/json' -d '{
"note": "test2",
}'
https://api.mercadolibre.com/orders/$ORDER_ID/notes/$NOTE_ID
Elimina notas
curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/$ORDER_ID/notes/$NOTE_ID
Bloquea ofertas
Aunque contamos con una prestación y flujos de prevención de fraude para mantener la seguridad de los compradores y vendedores, en algunas ocasiones puedes encontrar usuarios que, por algún motivo ofertan en las publicaciones. Estos casos pueden ser enviados a la lista negra para evitarles la posibilidad de ofertar.
¿Cómo bloqueo ofertas de un usuario específico?
Realiza una solicitud POST con el cust_id del usuario que deseas bloquear en el JSON y el tuyo en el url, como muestra el siguiente ejemplo:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'Content-Type: application/json' -d { user_id: {cust_id} } https://api.mercadolibre.com/users/{cust_Id}/order_blacklist
Consulta tu lista negra
Si deseas saber cuáles son los usuarios de tu lista negra, realiza una solicitud GET a la API con tu cust_id en el url:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$CUST_ID/order_blacklist
Elimina a un usuario de tu lista negra
Si ya no deseas bloquear a un usuario para que realice ofertas, puedes eliminarlo de tu lista negra al realizar una solicitud DELETE a la API con tu cust_id y el cust_id del usuario.
curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$YOUR_CUST_ID/order_blacklist/$CUST_ID
Entregar o devolver reserva
De acuerdo con las reglas de negocios de Mercado Libre, una vez completada la reserva, el vendedor debe informar la entrega del vehículo. Los compradores y vendedores consolidan sus reputaciones en base a la cantidad de vehículos reservados o entregados según sea el caso.
1. Vehículo entregado
Si la reserva ha sido concretada y se ha entregado el vehículo, deberás realizar una solicitud POST a la orden como se muestra a continuación:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'Content-Type: application/json' -d
'{
"fulfilled": true,
"rating": "positive"
}'
'https://api.mercadolibre.com/orders/$ORDER_ID/feedback'
Después que el comprador confirme que ha recibido el vehículo, se liberará el dinero de la reserva a tu cuenta.
2. Devolver reserva
Para devolver una reserva, realiza una solicitud POST a la orden como se muestra a continuación:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'Content-Type: application/json' -d
'{
"fulfilled": false,
"rating": "neutral"
}'
"https://api.mercadolibre.com/orders/$ORDER_ID/feedback"
El reembolso de la reserva será devuelto automáticamente al comprador.
Descripción de recursos
Completado Verdadero o Falso. Indica si la entrega del vehículo se concretó. Obligatorio.
Calificación Es ‘neutro’ en caso de ‘completado: ‘falso’ o ‘positivo’ en caso de ‘completado’: ‘verdadero’. Obligatorio.