Gestionar órdenes
Contenidos
→Obtener una orden
→Alertas de fraude (frenados de envíos)
→Calcular el monto total con envío
→Información de los productos en orders
→Buscar órdenes
→Filtrar órdenes
→Ordenar las órdenes
→Órdenes recientes
→Órdenes pendientes
→Órdenes archivadas
→Órdenes de Mercado Shops
→Buscar órdenes de Mercado Shops
→Estado de la orden
→Códigos de error
→Código de respuesta HTTP
Obtener 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:
Llamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/$ORDER_ID
Ejemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/768570754
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",
"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",
"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
},
"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.
description: descripción del estado.
buyer: información del comprador.
seller: 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.
taxes: monto con la sumatoria de impuestos que hay que pagar de la orden.
cancel_detail: detalle de la cancelación de la orden en las que se encuentra.
- group: agrupación lógica de la cancelación (mediations, fiscal, buyer, fraud, item, shipment, delivery, seller, internal).
- code: código de la causa de cancelación.
- description: descripción de la causa de cancelación.
- requested_by: quien solicita la cancelación (buyer, seller, Mercado Libre).
- date: fecha de la cancelación.
- application_id: ID de la aplicación que solicita la cancelación.
Alertas de fraude (frenados de envíos)
Luego de la aprobación del pago, y debido al relacionamiento con bancos y emisoras de tarjetas, podemos recibir alertas de que la venta en cuestión se trata de un fraude y para evitar un gasto finanaciero, la mercadería no debe ser enviada al comprador.
En este caso, la orden estará marcada con el tag "fraud_risk_detected" y enviaremos una notificación al tópico "orders_v2" con el ID de la orden.
Una vez identificada, la orden debe ser cancelada. En caso que el vendedor haya enviado el producto, será necesario comprobar el envío a través de Mercado Libre o Mercado Pago.
Calcular el monto total con envío
Con la respuesta que se obtiene en el llamado a GET /orders/:id y en el GET /shipments/:shipping_id (con el headerx-format-new: true) debes calcular:
total_amount_with_shipping = total_amount + taxes.amount + lead_time.cost |
---|
*En la misma moneda del ítem.
El total_amount y taxes.amount se obtienen del recurso /orders, mientras que lead_time.cost se obtiene de /shipments.
Llamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/currency_conversions/search?from=$CURRENCY_ID&to=$CURRENCY_ID
Ejemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/currency_conversions/search?from=ARS&to=BRL
Respuesta:
{
"ratio": 0.0704988
}
Información de los productos en orders
Esta búsqueda muestra toda la información de los productos que están en el mismo pedido:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/$ORDER_ID/product
Respuesta:
{
"attributes": [
{
"name": "IMEI",
"value": "111",
"id": 1
},
{
"name": "IMEI",
"value": "222",
"id": 2
},
{
"name": "entry_date",
"value": "01/01/2001",
"id": 3
}
]
}
Buscar órdenes
El recurso de búsqueda de órdenes te ayudará a buscar cada orden que pertenece a usuarios (vendedores o compradores) para quienes tienen un token válido.
Si realizas la búsqueda como vendedor, continuas filtrando dichas órdenes (canceladas).
Llamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/search
Filtrar órdenes
Para filtrar tus órdenes con status “paid” cuentas con los siguientes filtros:
item: ID o título
tags: puede ser varios estados separados por ','
tags.not: puede ser varios estados separados por ','
q: es un campo genérico que permite buscar por:
- id de la orden
- id del item
- título del ítem
- nickname de la contraparte
order.status: puede ser varios estados separados por ','
order.date_last_updated.from
order.date_last_updated.to
order.date_created.from
order.date_created.to
order.date_closed.from
order.date_closed.to
mediations.status: puede ser varios estados separados por ','
feedback.status: puede ser varios estados separados por ','
feedback.sale.rating: puede ser varios estados separados por ','
feedback.sale.fulfilled
feedback.purchase.rating: puede ser varios estados separados por ','
feedback.purchase.fulfilled
Ejemplo para filtrar órdenes por el status:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/search?seller=$SELLER_ID&order.status=paid
Ejemplo para buscar por múltiples criterios:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/search?seller=89660613&q=2032217210
Ejemplo para filtrar órdenes por fecha:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/search?seller=$SELLER_ID&order.date_created.from=2015-07-01T00:00:00.000-00:00&order.date_created.to=2015-07-31T00:00:00.000-00:00
Ejemplo de respuesta:
{
"query": "2032217210",
"results": [
{
"seller": {
"phone": {
"number": "11971427863",
"extension": "",
"area_code": null,
"verified": false
},
"alternative_phone": {
"number": "",
"extension": "",
"area_code": ""
},
"nickname": "VENDASDKMB",
"last_name": "Cheracomo",
"id": 239432672,
"first_name": "Demétrio",
"email": "dcherac.8m6k0q+2-ogiydgmrsge3tenby@mail.mercadolivre.com"
},
"payments": [
{
"reason": "Kit Com 03 Adesivo Spray 3m 75 Cola Silk Sublimação 300g",
"status_code": null,
"total_paid_amount": 129.95,
"operation_type": "regular_payment",
"transaction_amount": 129.95,
"date_approved": "2019-05-22T03:51:07.000-04:00",
"collector": {
"id": 239432672
},
"coupon_id": null,
"installments": 1,
"authorization_code": "008877",
"taxes_amount": 0,
"id": 4792155710,
"date_last_modified": "2019-05-22T03:51:07.000-04:00",
"coupon_amount": 0,
"available_actions": [
"refund"
],
"shipping_cost": 0,
"installment_amount": 129.95,
"date_created": "2019-05-22T03:51:05.000-04:00",
"activation_uri": null,
"overpaid_amount": 0,
"card_id": 203453778,
"status_detail": "accredited",
"issuer_id": "24",
"payment_method_id": "master",
"payment_type": "credit_card",
"deferred_period": null,
"atm_transfer_reference": {
"transaction_id": "135292",
"company_id": null
},
"site_id": "MLB",
"payer_id": 89660613,
"marketplace_fee": 14.290000000000001,
"order_id": 2032217210,
"currency_id": "BRL",
"status": "approved",
"transaction_order_id": null
}
],
"fulfilled": true,
"buying_mode": "buy_equals_pay",
"taxes": {
"amount": null,
"currency_id": null
},
"order_request": {
"change": null,
"return": null
},
"expiration_date": "2019-06-19T03:51:07.000-04:00",
"feedback": {
"sale": null,
"purchase": null
},
"shipping": {
"id": 27968238880
},
"date_closed": "2019-05-22T03:51:07.000-04:00",
"id": 2032217210,
"manufacturing_ending_date": null,
"hidden_for_seller": false,
"order_items": [
{
"item": {
"seller_custom_field": null,
"condition": "new",
"category_id": "MLB33383",
"variation_id": null,
"variation_attributes": [],
"seller_sku": null,
"warranty": "Garantia de 1 ano fabricante",
"id": "MLB1054990648",
"title": "Kit Com 03 Adesivo Spray 3m 75 Cola Silk Sublimação 300g"
},
"quantity": 1,
"differential_pricing_id": null,
"sale_fee": 14.29,
"listing_type_id": "gold_special",
"base_currency_id": null,
"unit_price": 129.95,
"full_unit_price": 129.95,
"base_exchange_rate": null,
"currency_id": "BRL",
"manufacturing_days": null
}
],
"date_last_updated": "2020-02-14T02:55:49.811Z",
"last_updated": "2019-05-28T15:16:04.000-04:00",
"comments": null,
"pack_id": null,
"coupon": {
"amount": 0,
"id": null
},
"shipping_cost": 0,
"date_created": "2019-05-22T03:51:05.000-04:00",
"application_id": "7092",
"pickup_id": null,
"status_detail": null,
"tags": [
"delivered",
"paid"
],
"buyer": {
"billing_info": {
"doc_number": "02183212950",
"doc_type": "CPF"
},
"phone": {
"number": "99962663",
"extension": "",
"area_code": "41",
"verified": false
},
"alternative_phone": {
"number": "30576339",
"extension": "",
"area_code": "41"
},
"nickname": "S.VICTORHUGO",
"last_name": "Schemberger",
"id": 89660613,
"first_name": "Victor Hugo",
"email": "vschemb.y14cdz+2-ogiydgmrsge3tenbz@mail.mercadolivre.com"
},
"total_amount": 129.95,
"paid_amount": 129.95,
"mediations": [],
"currency_id": "BRL",
"status": "paid"
}
],
"sort": {
"id": "date_asc",
"name": "Date ascending"
},
"available_sorts": [
{
"id": "date_desc",
"name": "Date descending"
}
],
"filters": [],
"paging": {
"total": 1,
"offset": 0,
"limit": 50
},
"display": "complete"
}
Ordenar las órdenes
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 han sido calificadas por ninguna de las partes (vendedor o comprador). Consulta utilizando como parámetros seller o buyer:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/search/recent?seller=$SELLER_ID
Órdenes pendientes
Esta búsqueda recupera 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
Órdenes de Mercado Shops
Identifica las órdenes de Mercado Shops cuando cuenten con el tag "mshops".
Ejemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H x-format-new: true https://api.mercadolibre.com/orders/$ORDER_ID
{
"id": 2063200914,
"date_created": "2019-06-24T15:53:04.000-04:00",
"date_closed": "2019-06-24T15:53:06.000-04:00",
"last_updated": "2019-06-24T15:53:06.000-04:00",
"manufacturing_ending_date": null,
"feedback": {...},
"mediations": [],
"comments": null,
"pack_id": null,
"pickup_id": null,
"order_request": {...},
"fulfilled": null,
"total_amount": 25,
"paid_amount": 31.9,
"coupon": {...},
"expiration_date": "2019-07-22T15:53:06.000-04:00",
"order_items": [...],
"currency_id": "BRL",
"payments": [...],
"shipping": {...},
"status": "paid",
"status_detail": null,
"tags": [
"mshops",
"not_delivered",
"paid"
],
"buyer": {...},
"seller": {...},
"taxes": {...}
}
Ó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
Buscar órdenes de Mercado Shops
Realiza una consulta con el tag mshops como por ejemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/search?seller=$SELLER_ID&tags=mshops
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ó.*
Códigos de error
Error_code | Mensaje de error | Descripción | Posible solución |
---|---|---|---|
order_not_found | orden no encontrada. | $order_id incorrecto. | No se puede encontrar la orden; consulta si el order_id es correcto. |
empty_order_id | El 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. |
invalid_order_id | ID 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_user | Falta de Token. | No existe un Token. | Se deberá enviar un Token. |
not_owned_order | El 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.invalid | El 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_found | El feedback no existe. | Error de respuesta. | Consulta si existe feedback para dar una respuesta. |
invalid_fulfilled | El 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_expired | El 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_exists | Ya existe respuesta para el feedback. | Error al dar respuesta sobre el feedback. | El feedback soporta una sola respuesta. |
Código de respuesta HTTP
Orders podrá devolver el código http 206 cuando no se haya podido obtener algún dato. Ten en cuenta que en la mayoría de los casos la información que recibas será suficiente para que puedas seguir trabajando. En el header de respuesta X-Content-Missing tendrás el nombre de los campos sin información, que pueden ser "buyer", "feedback", "mediations", "seller" y/o "shipping".
Llamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/$ORDER_ID
Respuesta:
< HTTP/1.1 206 Partial Content> X-Content-Missing: buyer, feedback
{
"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": - { },
},
"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": - { },
"shipping": - {
"id": 20676482441
},
"tags": - [
"paid",
"not_delivered",
],
}
Siguiente: Gestionar órdenes de Carrito.