Gestionar órdenes

Referencias
A - Recibes la notificación y obtén información específica de la orden
B - Verifica si la orden tiene el tag “pack_order”
C - Verifica si la orden tiene un envío asociado
D - Obtén los items del envío (pueden corresponder a órdenes distintas)
E - Valida la cantidad de órdenes del envío
F - Obtén la información de las órdenes asociadas al envío
G - Consulta la información del envío

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. Además, te recomendamos suscribirte al nuevo tópico orders feedback para estar actualizado sobre los feedbacks recibidos.

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/2000003508419013

Respuesta:

{
    "id": 2000003508419013,
    "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",
   	 "first_name": "Comprador de testes",
   	 "last_name": "da Silva",
    },
    "seller": {
   	 "id": "123456789",
    },
    "payments": [{
   	 "id": "596707837",
   	 "transaction_amount": 499,
   	 "currency_id": "BRL",
   	 "status": "approved",
   	 "date_created": null,
   	 "date_last_modified": null
    }],
    "feedback": {
   	 "purchase": null,
   	 "sale": null
    },
    "context": {
     "channel": "marketplace",
     "site": "MLB",
     "flows": [
     000]
  },
    "shipping": {
   	 "id": 20676482441
    },
    "tags": [
   	 "paid",
   	 "not_delivered"
    ]
}

Campos de respuesta:

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.

• item: publicación específica.
• cantidad: cantidad de items comprados.
• sale_fee: comisión de ventas.
• unit_price: precio unitário.

• channel: los canales de venta que hoy tiene el ítem. Valores posibles: mshops, proximity, mp-channel, marketplace.
• site: ID del sitio donde se originó la compra (MLA, MLB, MLM, etc)
• flows: es una lista de características del origen de la compra. Valores posibles cbt, subscription, reservation, catalog, contract, supermarket, 3x_campaign, high_concurrency, lite.

shipping: ID del envío para esta 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.
Nota:
- Las comisiones son calculadas al momento de la acreditación del pago, o sea, solo cuando el pedido si queda visible al vendedor y no cuando el pedido es creado .
- Ventas donde el pago falló pueden tener el medio de envío original cambiado ya que hay una recompra. Para casos donde la compra original tenia un envío asociado y la recompra un "to be agree", el status del envío si quedará status: "cancelled", substatus: "closed_by_user" y la venta necesita ser cancelada.
-Para obtener información del envío se debe realizar un llamado al recurso /shipments/shipping.id con el id obtenido en la orden.
-El array “context” trae información sobre flujo de generación de la compra y puede servir para análisis de los vendedores.



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.

Importante:
En caso de que taxes.currency_id sea distinto a items.currency_id debemos obtener el ratio de conversión:

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
    	}
	]
}

Nota:
Para ver las órdenes dentro de una compra carrito es necesario usar el recurso /packs. Ten en cuenta que el recurso /orders puede incluir muchos productos de la misma publicación en términos de cantidades.

Obtener descuentos aplicados en una venta

Utiliza el recurso /discounts para revisar los detalles de todos los descuentos que impactaron una venta. Ten en cuenta que los descuentos pueden venir desde una campaña (promoción), cupón o cashback, y que una venta puede tener más de un descuento aplicado.
Recuerda que actualmente se guardan órdenes creadas hasta 12 meses y si realizas la búsqueda como vendedor, filtras órdenes canceladas.




Llamada:

curl -X GET -H ‘Authorization: Bearer $ACCESS_TOKEN’ https://api.mercadolibre.com/orders/$ORDER_ID/discounts

Ejemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/2000003508419013/discounts

Respuesta:

{
    "details": [
        {
            "type": "coupon",
            "coupon": {
                "id": 569290732
            },
            "supplier": {
                "meli_campaign": "P-MLA4944001"
            },
            "items": [
                {
                    "quantity": 1,
                    "amounts": {
                        "total": 446.7,
                        "seller": 0
                    },
                    "id": "MLA922971037"
                }
            ]
        },
        {
            "type": "discount",
            "supplier": {
                "offer_id": "MLA922971037-abc123",
                "funding_mode": "sale_fee"
            },
            "items": [
                {
                    "quantity": 1,
                    "amounts": {
                        "total": 446.7,
                        "seller": 0
                    },
                    "id": "MLA922971037"
                }
            ]
        },
        {
            "type": "cashback",
            "items": [
                {
                    "element_id": 1,
                    "quantity": 1,
                    "id": "MLB1881365644",
                    "amounts": {
                        "total": 5.4,
                        "seller": 0
                    }
                }
            ],
            "supplier": {
                "campaign_id": "10116144"
            },
            "cashback": {
                "id": "2251800174114906"
            },
            "counter_currency": {
                "currency_id": "MCN",
                "value": 15.6784541
            }
        }
    ]
}

Campos de la respuesta

Cada descuento puede tener dentro del atributo details los siguientes campos dependiendo del type:

• coupon.id: Identificador del cupón.
• supplier: Proveedor de la campaña.
• meli_campaign: Campaña de descuentos asociada al cupón.
• offer_id: Identificador de la oferta, útil para recuperar nombre de campaña.
• funding_mode: Tipo de promoción obtenida desde IPA. Por ejemplo: sale_fee.
• ítems: Ítems a los que aplica el cupón.
• id: Identificador del ítem.
• quantity: Cantidad de ítems alcanzados por el descuento.
• amounts: Montos del cupón.
• total: Porción del descuento asociado al ítem (p * q).
• seller: Porción del descuento a cargo del vendedor (p * q).

Buscar órdenes

Puedes usar la funcionalidad /search del recurso /orders para realizar búsquedas con filtros. Ten en cuenta que /search no realiza ninguna acción si no está seguido por algún filtro.




Recuerda que actualmente se guardan órdenes creadas hasta 12 meses y si realizas la búsqueda como vendedor, filtras ó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 : fecha de la última modificación de la orden
order.date_last_updated.to: fecha de la última modificación de la orden
order.date_created.from
order.date_created.to
order.date_closed.from
order.date_closed.to
mediations.stage: puede ser varios estados separados por ','
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


Nota:
El filtro “q” no considera los valores first_name, last_name e email al buscar una orden.

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

Nota:
Utiliza hasta la hora y descarta la información de los minutos, segundos y milisegundos.

Ejemplo de respuesta:

{
	"query": "2032217210",
	"results": [{
		"seller": {
			"nickname": "VENDASDKMB",
			"id": 239432672
		},
		"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": 2000003508419013,
			"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": {
			"nickname": "S.VICTORHUGO",
			"id": 89660613
		},
		"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

Notas:
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 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": {...}
}




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.
partially_refunded La orden tiene devoluciones parciales de los pagos.
pending_cancel Cuando se quiere cancelar la orden pero nos cuesta devolver el pago.
cancelled Por alguna razón, la orden no se completó.*


Notas:
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 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.
- Si por alguna razón el vendedor califica como no concretada la operación, la orden toma el "status = confirmed". En caso de existir unaprobado este se devolverá automáticamente. Ten en cuenta, que una orden que no fue concretada por el vendedor por front se verá como "Cancelada" y por api quedara con "status: confirmed".


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",
  "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.