Gestiona reservas

Importante:

Esta funcionalidad sólo está disponible en Argentina, Brasil y México.

En todo anuncio de tipo “vehículo”, es posible encontrar el botón de reserva disponible, para que el comprador pueda garantizar la compra, reservando el vehículo pagando una seña, vía Mercado Pago. Siempre que existe una reserva, se genera una orden de pago. Una orden es una solicitud que realiza un cliente con intención de reservar un automóvil y puede terminar en una venta según el acuerdo con el vendedor. Estas condiciones se detallan en la orden, que también se replicará para las cuentas del comprador y del vendedor. En la orden encontrarás gran cantidad de información para completar sobre el vehículo como así también la posibilidad de reservar y/o descontar stock. Es decir, el integrador puede leer estas reservas (órdenes) en su sistema y avisar al cliente que su anuncio recibió una reserva. Más aún: también es posible implementar las acciones del vendedor de entrega/cancelación de la reserva. Todos estos puntos son explicados en las secciones abajo.

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.

Nota:

Del mismo modo que ocurre cada vez que se actualiza la información de una orden, en caso que se descubra que la compra fue fraudulenta, la marcaremos con el tag “fraud_risk_detected” y enviaremos una notificación con el topic “orders” y el ID de dicha orden.

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

Nota:

Para filtrar por fecha sólo se utiliza hasta la hora. Se descarta la información de los minutos, segundos y milisegundos.

¿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

Nota:

Por defecto ya viene con una orden date_asc aplicada. La fecha por la que se ordena es:
-Sellers por date_closed.
-Buyers por date_created.

Ó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ó.*

Notas:

Una orden puede ser cancelada por los siguiente motivos:
-Se requería el pago, pero después de cierto tiempo no se abonó, por eso se cancela automáticamente.
-Luego de efectuarse una transacción, por alguna razón el vendedor queda prohibido en el site.
-En caso que el vendedor devuelva la reserva, la orden pasará a “status = cancelled” y status_detail.code = feedback. En caso de existir un pago aprobado este se devolverá automáticamente.
-Si el vendedor confirma que entregó el vehículo y el comprador dice que no lo tiene, la orden toma el “status = cancelled” y status_detail.code = buyer. En caso de existir un pago aprobado este se devolverá automáticamente.
-Otra opción se debe a que la orden expira por lo tanto, también se tomará como “status = cancelled” y status_detail.code = expired_order. En caso de existir un pago aprobado este se devolverá automáticamente.

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”.

Nota:

Si quieres tomar la orden de la reserva selecciona la opción “orders_v2”.

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.