Gestiona ventas

Una orden es una solicitud que realiza un cliente para una publicación con intención de comprarlo conforme a una serie de condiciones que seleccionará en el flujo del proceso de compra online (checkout).
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.

Contenidos:

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": "Samsung Galaxy",
    	"variation_id": null,
    	"variation_attributes": [
    	],
  	},
  	"quantity": 1,
  	"unit_price": 499,
  	"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": - {
	"id": 20676482441,
	"shipment_type": "shipping",
	"status": "handling",
    "date_created": "2013-05-27T10:03:28.000-04:00",
	"receiver_address": - {
  	"id": 12345678,
  	"address_line": "Rua dos testes 123  ",
  	"zip_code": "01001000",
  	"city": - {
    	"id": "BR-SP-44",
    	"name": "São Paulo",
  	},
  	"state": - {
    	"id": "BR-SP",
    	"name": "São Paulo",
  	},
  	"country": - {
    	"id": "BR",
    	"name": "Brasil",
  	},
  	"latitude": null,
  	"longitude": null,
  	"comment": null,
	},
	"currency_id": "BRL",
	"cost": 0,
  },
  "tags": - [
	"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. Ver los valores posibles.
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.
payments Pagos relacionados con la orden.
feedback Información de feedback relacionada con la orden.
shipping Configuración del envío para este 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.
Nota: Del mismo modo que ocurre cada vez que se actualiza la información de una orden, en caso de que descubramos que la compra fue fraudulenta, marcaremos la orden con el tag “fraud_risk_detected” y te enviaremos una notificación con el topic “orders” y el ID de dicha orden.

¿Qué sucederá con la venta según su envío?

Sin Mercado Envíos: El vendedor será notificado vía e-mail o telefónicamente.

  • En caso de que el producto ya haya sido entregado y exista una prueba de ello, el vendedor queda cubierto ante un contracargo. Eso significa que no le descontaremos el dinero de la venta.
  • Si el producto todavía no se entregó, el vendedor deberá hacer el refund del dinero.
  • Para conocer cómo hacer un refund vía API consulta la documentación correspondiente.
  • Para más información te sugerimos leer la documentación de “Requisitos del Programa de Protección al Vendedor”.

Con Mercado Envíos: Si aún la etiqueta no ha sido impresa se cancelará la venta y se enviará una notificación al vendedor. Por otro lado, si el producto ya ha sido despachado Mercado Libre se comunicará con la empresa de envíos para que lo devuelva.

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”

¿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=

¿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 han sido calificadas por ninguna de las partes.
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:
confirmed
Estado inicial de un orden; aún sin haber sido pagada.
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ó.*
invalid
La orden fue invalidada porque provenía de un comprador malicioso.

*Nota: Una orden puede ser cancelada por los siguiente motivos:

  • Se requería aprobación del pago para descontar el stock, pero en el tiempo de proceso de aprobación el ítem fue pausado/finalizado por falta de stock por lo tanto se devuelve el pago al comprador.
  • 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.

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:

curl 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 (Para más información dirigete a:Categorías con pago inmediato.
  • 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”.

Cuando el pago se acredita por el monto total de la venta, la orden pasa del estado “payment_required” a “paid”. En ese momento:

  • Se hacen visibles para el seller.
  • Se descuenta el stock de item.
  • Se establece el campo date_closed.
  • Se agregan los datos de la contraparte.
  • Comienzan a enviarse además las notificaciones del topic “orders”.


2) Las órdenes que NO entran por este flujo se crean en estado “confirmed”. Desde ese momento:

  • Son visibles para el seller.
  • Se descuenta el stock de item.
  • Se establece el campo date_closed.
  • Tiene los datos de la contraparte.
  • Comienzan a enviarse además las notificaciones del topic “orders”/”created_orders”.

En caso de que se termine efectuando un pago a través de Mercado Pago y es acreditado por el monto total de la venta, la orden pasa del estado “confirmed” a “paid”.

Aclaración: En ambos casos, si durante el flujo de pago el comprador elige Mercado Envíos (ME2, sólo en países dónde está activo este servicio), el envío tendrá disponible para imprimir la etiqueta una vez que haya pasado a “paid” la order. Más info.

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

topicsconmensajeria

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.

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",
            	"variation_attributes": [],
            	"variation_id": null
        	},
        	"quantity": 1,
        	"unit_price": 591
    	}
	],
	"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=

Avanzado

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}

Referencias de Códigos de Error

Error_codeMensaje de errorDescripciónPosible solución
order_not_foundorden no encontrada.$order_id incorrecto.No se puede encontrar la orden; consulta si el order_id es correcto. (Más información)
empty_order_idEl ID de la orden no puede estar vacío.$order_id es nulo.El parámetro order_id no puede ser nulo; consulta el URL utilizado. (Más información)
invalid_order_idID de la orden inválido.$order_id incorrecto.El parámetro order_id debe ser un número entero. (Para buscar tus órdenes consulta este tema)
not_identified_userFalta de Token.No existe un Token.Se deberá enviar un Token.
not_owned_orderEl usuario no tiene acceso al orden.$seller o $buyer incorrectos.Para ver un orden, tu access_token debe ser generado desde el vendedor o el comprador.
caller.id.invalidEl caller.id no coincide con el comprador ni el vendedor.$seller o $buyer incorrectos.Para ver un orden, debes utilizar un ID del vendedor o del comprador.
feedback_not_foundEl feedback no existe.Error de respuesta.Consulta si existe feedback para dar una respuesta.
invalid_fulfilledEl parámetro ‘completado’ debe ser verdadero o falso.Error al dar feedback.Consulta el parámetro $fulfilled; debe ser booleano (elimina las comillas) y consulta si el parámetro $reason no es nulo en caso de $fulfilled: falso.
reply_time_expiredEl tiempo de respuesta expiró. Existe un período de 14 días para responder el feedback.Error al dar respuesta sobre el feedback.La respuesta se puede enviar en los 14 días posteriores a la fecha del feedback.
reply_already_existsYa existe respuesta para el feedback.Error al dar respuesta sobre el feedback.El feedback soporta una sola respuesta.



Siguiente:
API de mensajería.

Por favor califica del 1 al 5