Gestiona reservas

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 producto como así también la posibilidad de reservar y/o descontar stock.
Nota: esta funcionalidad sólo está disponible en Argentina y Brasil en fase inicial es decir, la reserva es notificada al vendedor vía e-mail por tiempo limitada.

Contenidos:

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.

Para conocer en detalle cómo funciona esta nueva funcionalidad en los vendedores te invitamos a hacer clic acá.

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 https://api.mercadolibre.com/orders/$ORDER_ID?access_token=$ACCESS_TOKEN

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.

https://api.mercadolibre.com/orders/search?buyer=buyer_id&access_token={...}

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

https://api.mercadolibre.com/orders/search?seller=seller_id&order.status=paid&access_token={...} 

En el caso de querer filtrar tus órdenes por fecha deberás hacerlo de la siguiente
manera:

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&access_token= 

Nota: ten en cuenta que 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”

https://api.mercadolibre.com/orders/search?seller={seller_id}&order.status=paid&sort=date_desc&access_token={...}

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:

https://api.mercadolibre.com/orders/search/recent?seller=seller_id&access_token={...} 

Búsqueda de las órdenes recientes de un comprador:

https://api.mercadolibre.com/orders/search/recent?buyer=buyer_id&access_token={...} 

Ó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:

https://api.mercadolibre.com/orders/search/archived?seller=seller_id&access_token={..
.} 

Búsqueda de las órdenes archivadas de un comprador:

https://api.mercadolibre.com/orders/search/archived?buyer=buyer_id&access_token={...} 

Ó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:

https://api.mercadolibre.com/orders/search/pending?seller=seller_id&access_token={...} 

Para buscar por comprador, reemplaza los parámetros como se indica a continuación:

https://api.mercadolibre.com/orders/search/pending?buyer=user_id&access_token={...} 

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 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:

url 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 sobre crear y configurar una
nueva aplicación, por favor consulta este link.

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 https://api.mercadolibre.com/orders/893431118?access_token=&ACCESS_TOKEN 

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

https://api.mercadolibre.com/payments?access_token= 

¿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

https://api.mercadolibre.com/collections/{collection_id}?access_token= 

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" -d '{  
 "note": "test", 
}' 
https://api.mercadolibre.com/orders/{order_Id}/notes?access_token=$ACCESS_TOKEN 

Visualiza notas de órdenes

curl -X GET https://api.mercadolibre.com/orders/{order_Id}/notes?access_token=$ACCESS_TOKEN

Cómo modificar una nota

curl -X PUT -H "Content-Type: application/json" -d '{ 
 "note": "test2", 
}' 
https://api.mercadolibre.com/orders/{order_Id}/notes/{note_Id}?access_token=$ACCESS_TOKEN 

Elimina notas

curl -X DELETE https://api.mercadolibre.com/orders/{order_Id}/notes/{note_Id}?access_token=$ACCESS_TOKEN 

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 "Content-Type: application/json" -d { user_id: {cust_id} } https://api.mercadolibre.com/users/{cust_Id}/order_blacklist?access_token=$ACCESS_TOKEN 

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 https://api.mercadolibre.com/users/{cust_id}/order_blacklist?access_token=$ACCESS_TOKEN 

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 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 "Content-Type: application/json" -d
'{
  "fulfilled": true,
  "rating": "positive"
}'

"https://api.mercadolibre.com/orders/{order_Id}/feedback?access_token=$ACCESS_TOKEN"

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 "Content-Type: application/json" -d
'{
  "fulfilled": false,
  "rating": "neutral"
}'

"https://api.mercadolibre.com/orders/{order_Id}/feedback?access_token=$ACCESS_TOKEN"

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.

Por favor califica del 1 al 5