Gerenciar orders
Referências
A - Recebe a notificação e obtém informações específicas sobre o pedido
B - Verifique se a ordem possui a tag "pack order"
C - Verifique se a ordem tem um envio associado
D - Obtenha os itens de envio (podem corresponder a orders diferentes)
E - Valide a quantidade de orders no envio
F - Obtenha as informações das orders associadas ao envio
G - Consulte as informações do envio
Receba uma ordem
Quando uma nova ordem é criada no usuário, os detalhes podem ser consultados através de uma solicitação ao recurso de order. Além disto recomendamos ativar o novo tópico de orders feedback para estar atualizado sobre os feedbacks recebidos.
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/$ORDER_IDExemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/2000003508419013Resposta:
{
"id": 2000003508897196,
"date_created": "2022-04-08T17:01:30.000-04:00",
"date_closed": "2022-04-08T17:01:33.000-04:00",
"last_updated": "2022-04-08T17:03:32.000-04:00",
"manufacturing_ending_date": null,
"comment": null,
"pack_id": 2000003508553677,
"pickup_id": null,
"order_request": {
"return": null,
"change": null
},
"fulfilled": null,
"mediations": [],
"total_amount": 50,
"paid_amount": 50,
"coupon": {
"id": null,
"amount": 0
},
"expiration_date": "2022-05-06T17:01:33.000-04:00",
"order_items": [
{
"item": {
"id": "MLB2608564035",
"title": "Camiseta Basica",
"category_id": "MLB31447",
"variation_id": 174390848694,
"seller_custom_field": null,
"variation_attributes": [
{
"id": "SIZE",
"name": "Tamanho",
"value_id": "2282666",
"value_name": "M"
},
{
"id": "COLOR",
"name": "Cor",
"value_id": "52049",
"value_name": "Preto"
}
],
"warranty": "Sem garantia",
"condition": "new",
"seller_sku": null,
"global_price": null,
"net_weight": null
},
"quantity": 1,
"requested_quantity": {
"value": 1,
"measure": "unit"
},
"picked_quantity": null,
"unit_price": 50,
"full_unit_price": 50,
"currency_id": "BRL",
"manufacturing_days": null,
"sale_fee": 12,
"listing_type_id": "gold_special"
}
],
"currency_id": "BRL",
"payments": [
{
"id": 21463688923,
"order_id": 2000003508897196,
"payer_id": 266272126,
"collector": {
"id": 478055419
},
"card_id": null,
"site_id": "MLB",
"reason": "Camiseta Basica",
"payment_method_id": "account_money",
"currency_id": "BRL",
"installments": 1,
"issuer_id": null,
"atm_transfer_reference": {
"company_id": null,
"transaction_id": null
},
"coupon_id": null,
"activation_uri": null,
"operation_type": "regular_payment",
"payment_type": "account_money",
"available_actions": [
"refund"
],
"status": "approved",
"status_code": null,
"status_detail": "accredited",
"transaction_amount": 50,
"transaction_amount_refunded": 0,
"taxes_amount": 0,
"shipping_cost": 0,
"coupon_amount": 0,
"overpaid_amount": 0,
"total_paid_amount": 50,
"installment_amount": null,
"deferred_period": null,
"date_approved": "2022-04-08T17:01:32.000-04:00",
"authorization_code": null,
"transaction_order_id": null,
"date_created": "2022-04-08T17:01:32.000-04:00",
"date_last_modified": "2022-04-08T17:01:44.000-04:00"
}
],
"shipping": {
"id": 41297142475
},
"status": "paid",
"status_detail": null,
"tags": [
"test_order",
"not_delivered",
"pack_order",
"paid"
],
"feedback": {
"buyer": null,
"seller": null
},
"context": {
"channel": "marketplace",
"site": "MLB",
"flows": []
},
"buyer": {
"id": 266272126,
"nickname": "TETE8127263",
"first_name": "Test",
"last_name": "Test"
},
"seller": {
"id": 478055419,
"nickname": "TEST9UIAUKUL",
"first_name": "Test",
"last_name": "Test",
"phone": {
"extension": "",
"area_code": "01",
"number": "1111-1111",
"verified": false
},
"alternative_phone": {
"area_code": "",
"extension": "",
"number": ""
}
},
"taxes": {
"amount": null,
"currency_id": null,
"id": null
}
}Há grande número de atributos conforme a ordem. A seguir, vamos ver uma descrição dos campos mais importantes.
id: identificador único da ordem.
date_created: data de criação da ordem.
date_closed: data de confirmação da ordem. Quando uma ordem muda pela primeira vez de status é definida como: confirmed / paid e descontada do estoque do item.
expiration_date: prazo limite para o usuário qualificar; após essa data, o feedback se torna visível, os pagamentos são emitidos (caso houver) e os encargos são criados.
status: status da ordem. Ver os valores possíveis.
status_detail: detalhe do status.
code: código do status.
description: descrição do status.
comprador: informações do comprador.
vendedor: informações do vendedor.
order_items: publicações na ordem.
- item: publicação específica.
- quantity: quantidade de itens comprados.
- sale_fee: comissão de vendas.
- unit_price: preço unitário.
payments: pagamentos relacionados à ordem.
feedback: ID de feedback relacionadas à ordem.
context: detalhe das características da criação de uma order.
- channel: os canais de venda que hoje tem este item. valores possíveis: mshops | proximity | mp-channel | marketplace.
- site: ID do site onde se originou a compra (MLA, MLB, MLM, etc)
- flows: é uma lista de características da origem da compra. Valores possíveus: cbt | subscription | reservation | catalog, contract | supermarket | 3x_campaign | high_concurrency | lite.
- group: agrupamento lógico de cancelamento (mediations, fiscal, buyer, fraud, item, shipment, delivery, seller, internal).
- code: código da causa do cancelamento.
- description: descrição da causa do cancelamento.
- requested_by: quem solicita o cancelamento (buyer, seller, Mercado Livre).
- date: data do cancelamento.
- application_id: ID da aplicação que solicita o cancelamento.
shipping: ID do envio para esta ordem.
total_amount: valor total da ordem.
currency_id: ID de moeda.
tags: lista das tags selecionadas pelo vendedor, como entregue, pago.
taxes: valor com a soma dos impostos a serem pagos pelo pedido.
cancel_detail: detalhe do cancelamento da venda.
Alertas de fraude (frenados de envíos)
Após a aprovação de um pagamento, devido ao relacionamento com bancos e emissoras de cartão, podemos receber alertas de que o pedido em questão se trata de uma fraude e que para evitar perda financeira, a mercadoria não deve ser enviada ao comprador.
Neste caso, o pedido é marcado com a tag "fraud_risk_detected" e enviamos uma notificação no topic "orders_v2" com o ID deste pedido.
Após identificado, o pedido deve ser cancelado. Caso o vendedor já tenha enviado a mercadoria, será necessário comprovar o envio através site do Mercado Livre ou Mercado Pago.
Cálculo do total_amount_with_shipping
Com a resposta obtida na chamada a GET /orders/:id e na GET /shipments/:shipping_id, ambas com o header x-format-new: true, deve realizar o seguinte cálculo:
| total_amount_with_shipping = total_amount + taxes.amount + lead_time.cost |
|---|
*Na mesma moeda do item.
O total_amount e taxes.amount se o obtém através do recurso /orders, já o lead_time.cost se obtém em /shipments.
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/currency_conversions/search?from=$CURRENCY_ID&to=$CURRENCY_IDExemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/currency_conversions/search?from=ARS&to=BRLResposta:
{
"ratio": 0.0704988
}Informações dos produtos em orders
Esta pesquisa mostrará todas as informações do(s) produtos que estão nesse mesmo pedido:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/$ORDER_ID/productResposta:
{
"attributes": [
{
"name": "IMEI",
"value": "111",
"id": 1
},
{
"name": "IMEI",
"value": "222",
"id": 2
},
{
"name": "entry_date",
"value": "01/01/2001",
"id": 3
}
]
}Consultar orders
O seguinte recurso vai ajudá-lo a pesquisar cada ordem de usuários (vendedores e compradores). Lembre-se que os pedidos criados são salvos por até 12 meses e se você pesquisar como vendedor, continuará a filtrar os pedidos cancelados.
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/search
Filtrar orders
Para filtrar seus pedidos com o status de contas "paid" com os seguintes filtros:
item: ID o título
tags: pode haver vários estados separados por ','
tags.not: pode haver vários estados separados por ','
q: é um campo genérico que permite pesquisar por:
- ID da orden
- ID do item
- título do item
- nickname da contraparte
order.status: pode haver vários estados separados por ','
order.date_last_updated.from : data da última modificação da order
order.date_last_updated.to: data da última modificação da order
order.date_created.from
order.date_created.to
order.date_closed.from
order.date_closed.to
mediations.stage: pode haver vários estados separados por ','
mediations.status: pode haver vários estados separados por ','
feedback.status: pode haver vários estados separados por ','
feedback.sale.rating: pode haver vários estados separados por ','
feedback.sale.fulfilled
feedback.purchase.rating: pode haver vários estados separados por ','
feedback.purchase.fulfilled
Exemplo para filtrar pedidos por status:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/search?seller=$SELLER_ID&order.status=paidExemplo para pesquisar por vários critérios:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/search?seller=89660613&q=2032217210Exemplo para filtrar pedidos por data:
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:00Exemplo de resposta:
{
"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 uma orden
Neste caso, você deve adicionar "sort" com o ID disponível da ordem que quiser aplicar, por exemplo: “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
Orders recentes
As orders recentes são as mais novas geradas para um usuário. A resposta incluirá orders em que a data atual for anterior à expiration_date e ainda não tenham sido qualificadas por ambas as partes (vendedor e comprador).. Pesquisa de orders recentes de um vendedor:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/search/recent?seller=$SELLER_IDOrders pendentes
Esta pesquisa recuperará todos as orders em status "pendente" e omitirá as canceladas automaticamente. Se você quiser ver as orders de um vendedor, envie o seller_id:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/search/pending?seller=$SELLER_IDOrders de Mercado Shops
As orders de Mercado Shops também estão disponíveis na API de Mercado Livre.
Para identificar essas orders, você deve utilizar a tag “mshops”.
Exemplo de ordem de Mercado Shops:
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": {
"sale": null,
"purchase": null
},
"mediations": [],
"comments": null,
"pack_id": null,
"pickup_id": null,
"order_request": {
"return": null,
"change": null
},
"fulfilled": null,
"total_amount": 25,
"paid_amount": 31.9,
"coupon": {
"id": null,
"amount": 0
},
"expiration_date": "2019-07-22T15:53:06.000-04:00",
"order_items": [
"item": {
"id": "MLB1231068128",
"title": "Teste Anúncio Me2 - Não Ofertar",
"category_id": "MLB271107",
"variation_id": null,
"seller_custom_field": null,
"variation_attributes": [],
"warranty": null,
"condition": "new",
"seller_sku": null
},
"quantity": 1,
"unit_price": 25,
"full_unit_price": 25,
"currency_id": "BRL",
"manufacturing_days": null
],
"currency_id": "BRL",
"payments": [
"id": 4898000077,
"order_id": 2000003508419013,
"payer_id": 419067349,
"collector": {
"id": 419059118
},
"card_id": 313381752,
"site_id": "MLB",
"reason": "Teste Anúncio Me2 - Não Ofertar",
"payment_method_id": "master",
"currency_id": "BRL",
"installments": 1,
"issuer_id": "24",
"atm_transfer_reference": {
"company_id": null,
"transaction_id": "1234567"
},
"coupon_id": null,
"activation_uri": null,
"operation_type": "regular_payment",
"payment_type": "credit_card",
"available_actions": [
"refund"
],
"status": "approved",
"status_code": null,
"status_detail": "accredited",
"transaction_amount": 25,
"taxes_amount": 0,
"shipping_cost": 6.9,
"coupon_amount": 0,
"overpaid_amount": 0,
"total_paid_amount": 31.9,
"installment_amount": 31.9,
"deferred_period": null,
"date_approved": "2019-06-24T15:53:05.000-04:00",
"authorization_code": "1234567",
"transaction_order_id": null,
"date_created": "2019-06-24T15:53:05.000-04:00",
"date_last_modified": "2019-06-24T15:53:05.000-04:00"
],
"shipping": {
"id": 28001747957
},
"status": "paid",
"status_detail": null,
"tags": [
"mshops",
"test_order",
"not_delivered",
"paid"
],
"buyer": {
"id": 419067349,
"nickname": "TT763866",
"first_name": "Test",
"last_name": "Test",
"seller": {
"id": 419059118,
"nickname": "TETE8288849",
"phone": {
"area_code": "01",
"extension": "",
"number": "1111-1111",
"verified": false
},
"alternative_phone": {
"area_code": "",
"extension": "",
"number": ""
},
"first_name": "Test",
"last_name": "Test"
},
"taxes": {
"amount": null,
"currency_id": null
}Orders arquivadas
Se você procurar uma ordem com expiration_date posterior à data atual ou que foi qualificada por ambas as partes, pode utilizar o recurso de pesquisa em orders arquivadas:
Pesquisa de orders arquivadas de um vendedor:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/search/archived?seller=$SELLER_IDPesquisa de orders arquivadas de um comprador:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/search/archived?buyer=$BUYER_IDConsultar pedidos de Mercado Shops
Para consultar os pedidos de Mercado Shops, basta consultar pela tag mshops como no exemplo a seguir:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/search?seller=$SELLER_ID&tags=mshopsStatus da ordem
Os status da ordem são:
confirmed Status inicial de uma ordem; ainda sem ter sido paga.
payment_required O pagamento da ordem deve ter sido confirmado para exibir as informações do usuário.
payment_in_process Há um pagamento relacionado à ordem, mais ainda não foi creditado.
partially_paid A ordem tem um pagamento associado creditado, porém, insuficiente.
paid A ordem tem um pagamento associado creditado.
partially_refunded A ordem tem devoluções paciais de seus pagamentos.
pending_cancel Quando a Ordem foi cancelada mas temos dificultdade para devolver o pagamento.
cancelled Por alguma razão, a ordem não foi completada.*
invalid A ordem foi invalidada por vir de um comprador malicioso.
Referência de códigos de erro
| Error_code | Mensagem de erro | Descrição | Possível solução |
|---|---|---|---|
| order_not_found | Pedido não encontrado. | $order_id incorreto. | O pedido não foi encontrado; verifique se o order_id é o correto. |
| empty_order_id | O ID do pedido deve ser preenchido, ele não pode ficar incompleto. | $order_id nulo. | O parâmetro order_id não pode ser nulo; consulte a URL utilizada. |
| invalid_order_id | ID do pedido inválido. | $order_id incorreto. | O parâmetro order_id deve ser um número inteiro. (Para buscar seus pedidos, consulte esse assunto). |
| not_identified_user | Usuário não identificado. | Usuário não identificado. | Enviar seu token. |
| not_owned_order | O usuário não pode acessar ao pedido. | $seller ou $buyer incorreto. | Para visualizar um pedido, seu token de acesso deve ser gerado a partir do vendedor ou do 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 | O feedback não existe. | Erro de resposta. | Verifique se existe feeedback para dar uma resposta. |
| invalid_fulfilled | O parâmetro "concluído"deve ser verdadeiro ou falso. | Erro ao enviar feedback. | Consulte o parâmetro $fulfilled; ele deve ser booleano (elimine as aspas) e verifique se o parâmetro $reason não é nulo, em caso de $fulfilled: falso. |
| reply_time_expired | Tempo de resposta expirado. Há um período de 14 dias para responder ao feedback. | Erro ao dar resposta sobre o feedback. | A resposta pode ser enviada durante os 14 dias posteriores à data do feedback. |
| reply_already_exists | Já existe resposta para o feedback. | Erro ao dar resposta sobre o feedback. | O feedback só aceita uma resposta. |
Referências de código de resposta HTTP
Orders começarão a devolver o código http 206 quando não for possível obter algum dado. Tenha em conta que na maioria dos casos a informação recebida será suficiente para que você possa seguir trabalhando.
No header de resposta X-Content-Missing estarão disponibilizados os nomes dos campos que podem não conter informações. São eles: "location", "geolocation" e/ou "seller_address".
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/$ORDER_IDResposta:
< 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",
"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",
],
}
Seguinte: Orders de carrinho
