Gerencie vendas
Conteúdos
→Receba uma ordem →Alertas de fraude (frenados de envíos) →Calcular o valor total com envio →Informações dos produtos em orders →Consultar ordens →Filtrar ordens →Ordenar uma ordem →Ordens recentes →Ordens pendentes →Ordens arquivadas →Ordens de Mercado Shops →Consultar pedidos de Mercado Shops →Status da ordem →Códigos de erro →Código de resposta HTTP
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 ordens:
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/2032217210Exemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/768570754Resposta:
{
"application_id": "7092",
"buyer": {
"alternative_phone": {
"area_code": "41",
"extension": "",
"number": "30576339"
},
"billing_info": {
"doc_number": "02183212950",
"doc_type": "CPF"
},
"email": "vschemb.y14cdz+2-ogiydgmrsge3tenbz@mail.mercadolivre.com",
"first_name": "Victor Hugo",
"id": 89660613,
"last_name": "Schemberger",
"nickname": "S.VICTORHUGO",
"phone": {
"area_code": "41",
"extension": "",
"number": "99962663",
"verified": false
}
},
"buying_mode": "buy_equals_pay",
"comments": null,
"coupon": {
"amount": 0,
"id": null
},
"currency_id": "BRL",
"date_closed": "2019-05-22T03:51:07.000-04:00",
"date_created": "2019-05-22T03:51:05.000-04:00",
"expiration_date": "2019-06-19T03:51:07.000-04:00",
"feedback": {
"purchase": null,
"sale": null
},
"fulfilled": true,
"hidden_for_seller": false,
"id": 2032217210,
"internal_tags": [],
"last_updated": "2019-05-28T15:16:04.000-04:00",
"manufacturing_ending_date": null,
"mediations": [],
"order_items": [
{
"base_currency_id": null,
"base_exchange_rate": null,
"currency_id": "BRL",
"differential_pricing_id": null,
"full_unit_price": 129.95,
"item": {
"category_id": "MLB33383",
"condition": "new",
"id": "MLB1054990648",
"seller_custom_field": null,
"seller_sku": null,
"title": "Kit Com 03 Adesivo Spray 3m 75 Cola Silk Sublimação 300g",
"variation_attributes": [],
"variation_id": null,
"warranty": "Garantia de 1 ano fabricante"
},
"listing_type_id": "gold_special",
"manufacturing_days": null,
"quantity": 1,
"sale_fee": 14.29,
"unit_price": 129.95
}
],
"order_request": {
"change": null,
"return": null
},
"pack_id": null,
"paid_amount": 129.95,
"payments": [
{
"activation_uri": null,
"atm_transfer_reference": {
"company_id": null,
"transaction_id": "135292"
},
"authorization_code": "008877",
"available_actions": [
"refund"
],
"card_id": 203453778,
"collector": {
"id": 239432672
},
"coupon_amount": 0,
"coupon_id": null,
"currency_id": "BRL",
"date_approved": "2019-05-22T03:51:07.000-04:00",
"date_created": "2019-05-22T03:51:05.000-04:00",
"date_last_modified": "2019-05-22T03:51:07.000-04:00",
"deferred_period": null,
"id": 4792155710,
"installment_amount": 129.95,
"installments": 1,
"issuer_id": "24",
"marketplace_fee": 14.290000000000001,
"operation_type": "regular_payment",
"order_id": 2032217210,
"overpaid_amount": 0,
"payer_id": 89660613,
"payment_method_id": "master",
"payment_type": "credit_card",
"reason": "Kit Com 03 Adesivo Spray 3m 75 Cola Silk Sublimação 300g",
"shipping_cost": 0,
"site_id": "MLB",
"status": "approved",
"status_code": null,
"status_detail": "accredited",
"taxes_amount": 0,
"total_paid_amount": 129.95,
"transaction_amount": 129.95,
"transaction_order_id": null
}
],
"pickup_id": null,
"seller": {
"alternative_phone": {
"area_code": "",
"extension": "",
"number": ""
},
"email": "dcherac.8m6k0q+2-ogiydgmrsge3tenby@mail.mercadolivre.com",
"first_name": "Demétrio",
"id": 239432672,
"last_name": "Cheracomo",
"nickname": "VENDASDKMB",
"phone": {
"area_code": null,
"extension": "",
"number": "11971427863",
"verified": false
}
},
"shipping": {
"id": 27968238880
},
"shipping_cost": 0,
"status": "paid",
"status_detail": null,
"tags": [
"delivered",
"paid"
],
"taxes": {
"amount": null,
"currency_id": null
},
"total_amount": 129.95
}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: informações de feedback relacionadas à ordem.
shipping: configuração 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.
- 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 do aplicação que solicita o cancelamento.
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
}
]
}Pesquisa de ordens
O recurso de pesquisa de ordens vai ajudá-lo a pesquisar cada ordem de usuários (vendedores e compradores) com token válido.
Se você pesquisar como vendedor, continuará a filtrar esses pedidos (cancelados).
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/search
Filtrar ordens
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
- firts_name, last_name, email ou nickname da contraparte
order.status: pode haver vários 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: 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": {
"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 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
Ordens recentes
As ordens recentes são os geradas mais recentemente para um usuário. A resposta incluirá ordens nas quais a data atual for anterior à expiration_date e ainda não tenham sido qualificadas por nenhuma das partes. Pesquisa de ordens recentes de um vendedor:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/search/recent?seller=$SELLER_IDOrdens pendentes
Esta pesquisa recuperará todos as ordens em status "pendente" e omitirá as canceladas automaticamente. Se você quiser ver as ordens de um vendedor, envie o seller_id:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/search/pending?seller=$SELLER_IDOrdens de Mercado Shops
As ordens de Mercado Shops também estão disponíveis na API de Mercado Livre.
Para identificar essas ordens, 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": 2063200914,
"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",
"email": "ttest.6hqmq6+2-ogiydmmzsgaydsnjx@mail.mercadolivre.com",
"first_name": "Test",
"last_name": "Test",
"billing_info": {
"doc_type": "CPF",
"doc_number": "78525276200"
},
"seller": {
"id": 419059118,
"nickname": "TETE8288849",
"email": "ttest.hpz2z6q+2-ogiydmmzsgaydsnjs@mail.mercadolivre.com",
"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
}Ordens 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 ordens arquivadas:
Pesquisa de ordens arquivadas de um vendedor:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/search/archived?seller=$SELLER_IDPesquisa de ordens 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.
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",
"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",
],
}
Seguinte: Ordens de carrinho
