Recursos Cross
Confira os principais recursos das nossas APIs
Documentação do
Você pode usar esta documentação para as seguintes unidades de negócio:
Gerenciar orders
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,
},
"taxes": {
"amount": null,
"currency_id": null,
"id": null
}
}Além disso, recomendamos ativar o novo tópico de orders feedback para estar atualizado sobre os feedbacks recebidos.
Campos de resposta:
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 à order.
feedback: ID de feedback relacionadas à order.
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 order.
total_amount: valor total da order.
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 dos 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
}
]
}Obter descontos aplicados em uma venda
Utilize o recurso /discounts para revisar os detalhes de todos os descontos que impactaram uma venda. Considere que os descontos podem vir desde uma campanha (promoção), cupom ou cashback, e que uma venda pode ter mais de um desconto aplicado.
Lembre-se que atualmente são salvas orders criadas até 12 meses, e se realizar uma busca como vendedor, serão filtradas ordens canceladas.
Chamada:
curl -X GET -H ‘Authorization: Bearer $ACCESS_TOKEN’ https://api.mercadolibre.com/orders/$ORDER_ID/discountsExemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/2000003508419013/discountsResposta:
{
"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 da resposta
Cada desconto pode ter os seguintes campos dentro do atributo details, dependendo do type:
- coupon.id: identificador do cupom.
- supplier: provedor da campanha.
- meli_campaign: campanha de descontos associada ao cupom.
- offer_id: identificador da oferta, útil para recuperar o nome da campanha.
- funding_mode: tipo de promoção obtida pela IPA. Por exemplo, sale_fee.
- ítems: itens aos que aplicam o cupom.
- id: identificador do item.
- quantity: quantidade de itens alcançados pelo desconto.
- amounts: valores de cupom.
- total: porção do desconto associado ao item (p * q).
- seller: porção do desconto por conta do vendedor (p * q).
Consultar orders
Você pode usar a funcionalidade /search do recurso /orders para realizar buscas filtradas. Note que search não realiza nenhuma ação se não é seguido por um filtro.
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 order
- 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 order
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 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
}Consultar 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 order
Os status da order são:
confirmed Status inicial de
uma order; ainda sem ter sido paga.
payment_required
O pagamento da order deve ter sido confirmado para exibir as informações do
usuário.
payment_in_process Há um pagamento
relacionado à order, mais ainda não foi aprovado.
partially_paid
A order tem um pagamento associado creditado, porém, insuficiente.
paid A order tem um pagamento associado aprovado.
partially_refunded A order tem devoluções paciais de seus
pagamentos.
pending_cancel Quando a order foi cancelada mas temos
dificultdade para devolver o pagamento.
cancelled Por alguma razão, a order não foi completada.*
invalid A order 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 uma order, deve utilizar um ID do vendedor ou do 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",
},
"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