Gerencie vendas

Uma ordem é um pedido realizado por um cliente para um anúncio com a intenção de comprar conforme uma série de condições que ele irá escolher no fluxo do processo de compra online (checkout). Estas condições são detalhadas na ordem, que será replicada nas contas do comprador e do vendedor. A ordem contém grande quantidade de informações a serem preenchidas sobre o produto, bem como a possibilidade de reservar e/ou descontar estoque.

Conteúdos

→Receba uma ordem
→Cálculo do total_amount_with_shipping
→O que acontecerá com a venda segundo seu envio?
→Pesquisa de ordens
→Informações dos produtos em orders
→Como filtrar?
→Como ordenar a consulta
→Ordens recentes
→Ordens de Mercado Shops
→Como consultar pedidos de Mercado Shops
→Ordens arquivadas
→Ordens pendentes
→Status da ordem
→Fluxo de Mercado Pago obrigatório (somente para países com MP)
→Fluxo de devolução de dinheiro em conta por vendas canceladas
→Como seu app sabe de uma compra?
→Receber notificação
→Pagamentos
→Cenário de múltiplos pagamentos
→Como posso saber se existem dois pagamentos?
→Como obter informação de um pagamento?
→Como obter informação do pagamento como vendedor?
→Notas de ordens
→Como adicionar uma nota a uma ordem
→Visualize notas de ordens
→Como alterar uma nota
→Elimine notas
→Bloquear ofertas
→Como bloqueio ofertas de um usuário específico?
→Consulte sua lista negra
→Elimine um usuário de sua lista negra
→Referência de códigos de erro
→Referências de 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 https://api.mercadolibre.com/orders/$ORDER_ID?access_token=$ACCESS_TOKEN

Exemplo:

curl -X GET https://api.mercadolibre.com/orders/768570754?access_token=$ACCESS_TOKEN

Resposta:

{
  "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",
  ],
}

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

Nota:
Da mesma maneira que cada vez que a informação de uma ordem é atualizada, se descobrirmos que a compra foi fraudulenta, marcaremos a ordem com a tag "fraud_risk_detected" e enviaremos uma notificação para você com o topic "orders" e a ID da ordem.
Para obter as informações de envio é necessário fazer uma chamada ao recurso /shipments/shipping.id com o id informado na ordem. Visite nosso guia de shipments.
Para pedidos ME1, Custom ou entrega a combinar, disponibilizaremos nos dados do comprador o telefone para contato sempre que esta informação estiver cadastrada na conta. Exemplo:
"phone": - {
"area_code": "11",
"number": "12345678",
"extension": null,
},

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 * + shipping_options.cost * + 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.

Importante:
Nos casos em que taxes.currency_id é diferente de items.currency_id é necessário realizar a conversão.

Chamada:

curl -X GET  https://api.mercadolibre.com/currency_conversions/search?from=$CURRENCY_ID&to=$CURRENCY_ID

Exemplo:

curl -X GET  https://api.mercadolibre.com/currency_conversions/search?from=ARS&to=BRL

Resposta:

{
  "ratio": 0.0704988
}


O que acontecerá com a venda segundo seu envio?

Sem Mercado Envios: O vendedor será informado via email ou telefonicamente.

  • Caso o produto tenha sido entregue e exista prova disso, o vendedor fica protegido perante um contra-encargo. Isso significa que o dinheiro da venda não lhe será descontado.
  • Se o produto ainda não foi entregue, o vendedor deverá fazer o refund do dinheiro.
  • Para saber como fazer um refund via API confira Devoluções e cancelamentos.
  • Se quiser mais informações, sugerimos a leitura da documentação de Requisitos do Programa de Proteção ao Vendedor.

Com Mercado Envios: Caso a etiqueta ainda não tenha sido impressa, a venda será cancelada e uma notificação será enviada ao vendedor. Além disso, se o produto já foi enviado, Mercado Livre entrará em contato com a empresa de envios para este ser retornado.


Pesquisa de ordens

O recurso de pesquisa de ordens vai ajudá-lo a pesquisar cada ordem de usuários com token válido.

Chamada:

curl -X GET https://api.mercadolibre.com/orders/search?buyer=$BUYER_ID&access_token=$ACCESS_TOKEN
Nota:
Você pode ver os pedidos cancelados manualmente, ou seja, com status manually_cancelled e aqueles com um item removido, usando a pesquisa como comprador. Se você pesquisar como vendedor, continuará a filtrar esses pedidos (cancelados).

Exemplo:

curl -X GET https://api.mercadolibre.com/orders/search?buyer=89660613&q=2032217210&access_token=$ACCESS_TOKEN

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"
}
Importante:
A partir de 1 de julho, removeremos o campo total_amount_with_shipping da resposta e o bloco de remessa conterá apenas seu ID. Para obter todas as informações relacionadas ao envio do pedido, recomendamos que você use el recurso /shipments/:shipping_id.


Informações dos produtos em orders

Esta pesquisa mostrará todas as informações do(s) produtos que estão nesse mesmo pedido:

Nota:
Para os pedidos do Fulfillment, o IMEI está sendo trazido também direto na Nota Fiscal.
curl -X GET https://api.mercadolibre.com/orders/$ORDER_ID/product?access_token=$ACCESS_TOKEN

Resposta:

{
  "attributes": [
        {
            "name": "IMEI",
          "value": "111",
            "id": 1
      },
        {
            "name": "IMEI",
          "value": "222",
            "id": 2
      },
        {
            "name": "entry_date",
          "value": "01/01/2001",
            "id": 3
      }
  ]
}


Como filtrar?

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:

curl  -X GET https://api.mercadolibre.com/orders/search?seller=seller_id&order.status=paid&access_token=$ACCESS_TOKEN

Para filtrar suas ordens por data, você deverá fazer o seguinte:

curl  -X GET 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&access_token=
Notas:
leve em conta que para filtrar por data somente se utiliza até a hora. Informação de minutos, segundos e milissegundos é descartada.


Como ordenar a consulta

Neste caso, você deve adicionar "sort" com o ID disponível da ordem que quiser aplicar, por exemplo: “date_desc”

curl  -X GET https://api.mercadolibre.com/orders/search?seller={seller_id}&order.status=paid&sort=date_desc&access_token={...}
Notas:
Por default, uma ordem date_asc já vem aplicada. A data segundo a qual é organizada é:
- Sellers por date_closed.
- Buyers por date_created.


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 https://api.mercadolibre.com/orders/search/recent?seller=$SELLER_ID&access_token=$ACCESS_TOKEN

Pesquisa de ordens recentes de um comprador:

curl -X GET https://api.mercadolibre.com/orders/search/recent?buyer=$BUYER_ID&access_token=$ACCESS_TOKEN


Ordens 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 x-format-new: true https://api.mercadolibre.com/orders/$ORDER_ID?access_token=$ACCESS_TOKEN

{
    "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
    
}

A estrutura do Json é a mesma que a das ordens de Mercado Livre.
Os pedidos de Mercado Shops também podem ser de carrinho. Para isso, consulte a documentação Gerenciamento de Ordens de Carrinho.


Como 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 https://api.mercadolibre.com/orders/search?seller=$SELLER_ID&tags=mshops&access_token=$ACCESS_TOKEN


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 https://api.mercadolibre.com/orders/search/archived?seller=$SELLER_ID&access_token=$ACCESS_TOKEN

Pesquisa de ordens arquivadas de um comprador:

curl -X GET https://api.mercadolibre.com/orders/search/archived?buyer=$BUYER_ID&access_token=$ACCESS_TOKEN


Ordens 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 https://api.mercadolibre.com/orders/search/pending?seller=$SELLER_ID&access_token=$ACCESS_TOKEN

Para pesquisar por comprador, substitua os parâmetros como é mostrado a seguir:

curl -X GET https://api.mercadolibre.com/orders/search/pending?buyer=$USER_ID&access_token=$ACCESS_TOKEN


Status 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.

Notas:
Uma ordem pode ser cancelada pelos seguintes motivos:
- Requeria aprovação do pagamento para descontar do estoque, mas, no tempo de processo de aprovação, o item foi pausado/finalizado por falta de estoque, portanto, o pagamento é retornado ao comprador.
- Requeria pagamento, mas, após certo tempo, não foi paga, por isso é automaticamente cancelada.
- Após uma transação ter sido efetuada, o vendedor é proibido no site por alguma razão.
- Se por alguma razão o vendedor qualificar a operação como não concretizada, a ordem assume o "status = confirmed". Caso exista um pagamento aprovado, este será automaticamente devolvido. Lembre que uma ordem não concretizada pelo vendedor será visualizada como "Cancelada" por front e por api terá "status = confirmed".


Fluxo de Mercado Pago obrigatório (somente para países com Mercado Pago)

Como saber se um site tem Mercado Pago ativo? Para obter essa informação, você deve realizar a seguinte chamada:

curl -X GET https://api.mercadolibre.com/sites/MLB

Caso você obtenha "MLBMP" como resposta dentro dos "payment_method_ids", poderá trabalhar sem problemas com este fluxo. Aclaração: MLBMP é o ID do método de pagamento Mercado Pago:

curl -X GET https://api.mercadolibre.com/payment_methods/MLBMP

Dentro da nossa plataforma, você vai encontrar ordens que podem entrar pelo fluxo obrigatório de Mercado Pago como único meio de pagamento e outras que não. Os cenários apresentados a seguir são aqueles em que você pode encontrar esta opção de maneira obrigatória:

Agora vamos explicar como é o funcionamento geral das ordens, estejam elas dentro deste fluxo ou não: 1) Ordens dentro deste fluxo são criadas em status “payment_required”. Nesse momento, têm as seguintes características:

  • Não são visíveis para o seller.
  • O estoque não é descontado do item.
  • Não têm o campo date_closed estabelecido.
  • Não têm dados da contraparte.
  • Somente é enviada a notificação do topic "create_orders".

Quando o pagamento é creditado pelo valor total da venda, a ordem passa do status "payment_required" para "paid". Nesse momento:

  • Passam a ser visíveis para o seller.
  • O item é descontado do estoque.
  • O campo date_closed é estabelecido.
  • São adicionados os dados da contraparte.
  • Também começam a ser enviadas as notificações do topic "orders".

Ordens que NÃO estão dentro deste fluxo são criadas em status “confirmed”. A partir desse momento:

  • São visíveis para o seller.
  • O item é descontado do estoque.
  • O campo date_closed é estabelecido.
  • Contêm os dados da contraparte.
  • Também começam a ser enviadas as notificações do topic "orders"/”created_orders”.

Caso seja efetuado um pagamento através de Mercado Pago e seja creditado pelo valor total de venda, a ordem passa do estado "confirmed" para "paid".

Nota:
Em ambos casos, se durante o fluxo de pagamento o comprador escolher Mercado Envios 2 (ME2) somente em países onde está ativo o serviço), o envio terá disponível para imprimir a etiqueta, uma vez que a Order passar para o status paid.

Fluxo de devolução de dinheiro em conta por vendas canceladas

Importante:
Só disponível para vendedores do México e, em breve, da Argentina e do Brasil.

Caso os cancelamentos sejam feitos pelos compradores com boa reputação e que realizarem pagamentos no cartão de crédito ou débito receberão automaticamente a devolução em dinheiro na conta do Mercado Pago.
Assim, a ordem de compra muda o status em relação aos outros fluxos. As mudanças serão:

  • status = paid
  • Nova tag: unfulfilled
Nota:
A ordem jamais terá status cancelled pois a devolução com dinheiro em conta gera que o pagamento deve ser concretizado. No pagamento da ordem, você vai encontrar a tag refund_account_money.


Como seu app sabe de uma compra?

A criação de uma ordem é um evento que se produz do lado do Mercado Livre, portanto, você deverá se cadastrar no nosso fedd de orders para saber em tempo real quando esse evento ocorre. Vá para o nosso Gerenciador de Aplicativos e edite as Configurações de Notificações de seu aplicativo. Mais informações sobre criar e configurar um novo aplicativo neste link.
Você deve selecionar um Callback URL: configure a URL pública do domínio onde você quiser receber todas as notificações do Mercado Livre. Por exemplo: “https://backend.soleorigami.com/notification”.


topicsconmensajeria

Esta configuração permite que você interaja com as notificações do Mercado Livre. Todos os eventos (como pagamento e envio) relacionados a uma ordem serão notificados a seu callback URL.


Receber notificação

Mercado Livre vai enviar notificações através de uma mensagem POST contendo informações. O atributo mais importante da mensagem é o user_id, relacionado à notificação; o segundo em importância é o recurso. O recurso é o elemento atualizado ou criado.

{
  "user_id": 1234,
  "resource": "/orders/731867397",
  "topic": "orders",
  "received": "2011-10-19T16:38:34.425Z",
  "application_id" : 14529
  "sent" : "2011-10-19T16:40:34.425Z",
  "attempts" : 0
}

After receiving the notification, you must send an acknowledgment [acknowledgment] (ACK 200) to Mercado Libre to stop receiving it.


Pagamentos

Mercado Pago é a plataforma de pagamentos de Mercado Livre. Se você quiser integrar uma solução de pagamentos em sua plataforma, deve consultar o site de desenvolvedores de Mercado Pago.


Cenário de múltiplos pagamentos

Em alguns casos, quando o pagamento é rejeitado porque o cartão de crédito atinge o limite, permitimos que os usuários adicionem outro pagamento com um segundo cartão de crédito.


Como posso saber se existem dois pagamentos?

Quando você faz uma solicitação GET para a API de pedidos, poderá ver que dentro do conjunto de pagamentos existem dois ID com os detalhes de cada pagamento.
Exemplo:

curl -X GET https://api.mercadolibre.com/orders/893431118?access_token=&ACCESS_TOKEN

Respuesta

{
  "buyer": {
      "alternative_phone": {
          "area_code": null,
          "extension": null,
          "number": ""
      },
      "billing_info": {
          "doc_number": "67045427794",
          "doc_type": "CPF"
      },
      "email": "test_user_21963158@testuser.com",
      "first_name": "Test",
      "id": 160903317,
      "last_name": "Test",
      "nickname": "TETE2022123",
  },
  "coupon": {
      "amount": 0,
      "id": null
    },
  "currency_id": "BRL",
  "date_closed": null,
  "date_created": "2014-10-26T22:46:18.000-04:00",
  "feedback": {
      "purchase": null,
      "sale": null
  },
  "id": 893431118,
  "last_updated": "2014-10-26T22:50:10.000-04:00",
    "mediations": [],
  "order_items": [
      {
          "currency_id": "BRL",
          "item": {
              "id": "MLB600034093",
              "title": "Item De Testeo, Por Favor No Ofertar --kc:off",
              "variation_attributes": [],
              "variation_id": null
          },
          "quantity": 1,
          "unit_price": 591
      }
  ],
  "paid_amount": 591,
  "payments": [
      {
          "activation_uri": null,
          "atm_transfer_reference": {
              "company_id": null,
                "transaction_id": null
          },
            "available_actions": [],
          "card_id": null,
          "collector": {
              "id": 169648308
          },
          "coupon_amount": 0,
          "coupon_id": null,
          "currency_id": "BRL",
          "date_created": "2014-10-26T22:48:46.000-04:00",
            "date_last_modified": "2014-10-27T00:51:53.000-04:00",
          "id": 885920310,
          "installments": 1,
          "issuer_id": "25",
          "operation_type": "regular_payment",
          "order_id": 893431118,
          "overpaid_amount": 0,
          "payer_id": 160903317,
            "payment_method_id": "visa",
          "payment_type": "credit_card",
          "reason": "Item De Testeo, Por Favor No Ofertar --kc:off",
          "shipping_cost": 0,
          "site_id": "MLB",
          "status": "approved",
          "status_code": null,
          "status_detail": "accredited",
            "total_paid_amount": 296,
            "transaction_amount": 296
      },
      {
          "activation_uri": null,
            "atm_transfer_reference": {
              "company_id": null,
                "transaction_id": null
          },
            "available_actions": [],
          "card_id": null,
          "collector": {
              "id": 169648308
          },
          "coupon_amount": 0,
          "coupon_id": null,
          "currency_id": "BRL",
          "date_created": "2014-10-26T22:50:10.000-04:00",
            "date_last_modified": "2014-10-26T22:50:21.000-04:00",
          "id": 885920410,
          "installments": 3,
          "issuer_id": "25",
          "operation_type": "regular_payment",
          "order_id": 893431118,
          "overpaid_amount": 0,
          "payer_id": 160903317,
            "payment_method_id": "visa",
          "payment_type": "credit_card",
          "reason": "Item De Testeo, Por Favor No Ofertar --kc:off",
          "shipping_cost": 0,
          "site_id": "MLB",
          "status": "approved",
          "status_code": null,
          "status_detail": "accredited",
            "total_paid_amount": 315.62,
            "transaction_amount": 295
      }
  ],
  "seller": {
      "alternative_phone": {
          "area_code": null,
          "extension": null,
          "number": ""
      },
      "email": "test_user_70385259@testuser.com",
      "first_name": "Test",
      "id": 169648308,
      "last_name": "Test",
      "nickname": "TETE6072468",
      "phone": {
          "area_code": "01",
          "extension": null,
          "number": "1111-1111"
      }
  },
  "shipping": {
      "status": "null"
  },
  "status": "paid",
  "status_detail": null,
  "tags": [
      "not_delivered",
      "paid"
  ],
  "total_amount": 591,

}


Como obter informação de um pagamento?

Para obter informação do pagamento de uma ordem, deverá recorrer ao recurso payments da API do Mercado Pago. Dependendo do token, se reconhecerá se a consulta é do buyer ou do seller e devolverá a informação correta.

curl -X GET https://api.mercadopago.com/v1/payments/$PAYMENT_ID?access_token=$ACCESS_TOKEN

Resposta:

Exemplo com token do vendedor

GET https://api.mercadopago.com/v1/payments/3506756222?access_token
{
  "counter_currency": null,
  "acquirer_reconciliation": [
  ],
  "statement_descriptor": "MERCADOPAGO",
  "captured": true,
  "fee_details": [
    {
      "amount": 487.2,
      "fee_payer": "payer",
      "type": "financing_fee"
    }
  ],
  "acquirer": null,
  "date_last_updated": "2018-03-05T10:06:55.000-04:00",
  "date_created": "2018-03-05T10:06:54.000-04:00",
  "id": 3506756222,
  "merchant_account_id": null,
  "issuer_id": "157",
  "date_of_expiration": null,
  "external_reference": "1653027692",
  "order": {
    "id": "1653027692",
    "type": "mercadolibre"
  },
  "transaction_amount": 3500,
  "description": "Maquina Industrial Recta Marca ",
  "card": {
    "id": null,
    "first_six_digits": "371772",
    "expiration_month": 10,
    "cardholder": {
      "identification": {
        "number": null,
        "type": null
      },
      "name": "JOAN C GONZALEZ GUZMAN"
    },
    "date_last_updated": "2018-03-05T10:06:54.000-04:00",
    "date_created": "2018-03-05T10:06:54.000-04:00",
    "expiration_year": 2019,
    "last_four_digits": "1001"
  },
  "transaction_details": {
    "total_paid_amount": 3987.2,
    "acquirer_reference": null,
    "payment_method_reference_id": null,
    "net_received_amount": 3500,
    "financial_institution": null,
    "payable_deferral_period": null,
    "installment_amount": 443.02,
    "external_resource_url": null,
    "overpaid_amount": 0
  },
  "coupon_amount": 0,
  "merchant_number": null,
  "call_for_authorize_id": null,
  "metadata": {
  },
  "currency_id": "MXN",
  "money_release_schema": null,
  "collector_id": 277582551,
  "status": "approved",
  "sponsor_id": null,
  "deduction_schema": null,
  "payment_method_id": "amex",
  "additional_info": {
    "items": [
      {
        "id": "MLM610028711",
        "title": "Maquina Industrial Recta Marca",
        "picture_url": null,
        "description": null,
        "category_id": "MLM184696",
        "quantity": "1",
        "unit_price": "3500"
      }
    ]
  },
  "processing_mode": "aggregator",
  "status_detail": "accredited",
  "binary_mode": false,
  "operation_type": "regular_payment",
  "installments": 9,
  "money_release_date": "2018-03-26T10:06:55.000-04:00",
  "payer": {
    "id": "53745235",
    "first_name": "Joan Carlos",
    "phone": {
      "extension": null,
      "area_code": null,
      "number": "5558800201"
    },
    "email": null,
    "identification": {
      "number": "83092109600",
      "type": "IFE"
    },
    "last_name": "Gonzalez Guzman",
    "entity_type": null,
    "type": "registered"
  },
  "notification_url": null,
  "transaction_amount_refunded": 0,
  "refunds": [
  ],
  "date_approved": "2018-03-05T10:06:55.000-04:00",
  "authorization_code": "211118",
  "payment_type_id": "credit_card",
  "live_mode": true
}


Ejemplo con token de comprador

GET https://api.mercadopago.com/v1/payments/3506756222?access_token
{
  "counter_currency": null,
  "acquirer_reconciliation": [
  ],
  "statement_descriptor": "MERCADOPAGO",
  "captured": true,
  "fee_details": [
    {
      "amount": 487.2,
      "fee_payer": "payer",
      "type": "financing_fee"
    }
  ],
  "acquirer": null,
  "date_last_updated": "2018-03-05T10:06:55.000-04:00",
  "date_created": "2018-03-05T10:06:54.000-04:00",
  "id": 3506756222,
  "merchant_account_id": null,
  "payer_id": 53745235,
  "collector": {
    "id": 277582551,
    "first_name": "Belem",
    "phone": {
      "extension": null,
      "area_code": null,
      "number": "5547588284"
    },
    "email": null,
    "identification": {
      "number": null,
      "type": null
    },
    "last_name": "Jimenez"
  },
  "issuer_id": "157",
  "date_of_expiration": null,
  "external_reference": "1653027692",
  "order": {
    "id": "1653027692",
    "type": "mercadolibre"
  },
  "transaction_amount": 3500,
  "description": "Maquina Industrial Recta Marca ",
  "card": {
    "id": null,
    "first_six_digits": "371772",
    "expiration_month": 10,
    "cardholder": {
      "identification": {
        "number": null,
        "type": null
      },
      "name": "JOAN C GONZALEZ GUZMAN"
    },
    "date_last_updated": "2018-03-05T10:06:54.000-04:00",
    "date_created": "2018-03-05T10:06:54.000-04:00",
    "expiration_year": 2019,
    "last_four_digits": "1001"
  },
  "transaction_details": {
    "total_paid_amount": 3987.2,
    "acquirer_reference": null,
    "payment_method_reference_id": null,
    "net_received_amount": 3500,
    "financial_institution": null,
    "payable_deferral_period": null,
    "installment_amount": 443.02,
    "external_resource_url": null,
    "overpaid_amount": 0
  },
  "coupon_amount": 0,
  "merchant_number": null,
  "call_for_authorize_id": null,
  "metadata": {
  },
  "currency_id": "MXN",
  "money_release_schema": null,
  "status": "approved",
  "sponsor_id": null,
  "deduction_schema": null,
  "payment_method_id": "amex",
  "additional_info": {
    "items": [
      {
        "id": "MLM610028711",
        "title": "Maquina Industrial Recta Marca",
        "picture_url": null,
        "description": null,
        "category_id": "MLM184696",
        "quantity": "1",
        "unit_price": "3500"
      }
    ]
  },
  "processing_mode": "aggregator",
  "status_detail": "accredited",
  "binary_mode": false,
  "operation_type": "regular_payment",
  "installments": 9,
  "differential_pricing_id": null,
  "money_release_date": "2018-03-26T10:06:55.000-04:00",
  "notification_url": null,
  "transaction_amount_refunded": 0,
  "refunds": [
  ],
  "date_approved": "2018-03-05T10:06:55.000-04:00",
  "authorization_code": "211118",
  "payment_type_id": "credit_card",
  "live_mode": true
}


Como obter informação do pagamento como vendedor?

Para obter informação do pagamento desde o rol vendedor, o recurso que deverá utilizar com o payment_id é “collections”.
Chamada:

curl -X GET https://api.mercadopago.com/v1/payments/$PAYMENT_ID?access_token=$ACCESS_TOKEN


Avanzado

Notas de ordens

Uma nota é uma anotação que os vendedores podem adicionar às ordens. As notas podem ter até 300 caracteres e, após terem sido publicadas, é possível alterá-las ou eliminá-las.


Como adicionar uma nota a uma ordem

curl -X POST -H "Content-Type: application/json" -d '{   
    "note": "test",
}' https://api.mercadolibre.com/orders/$ORDER_ID/notes?access_token=$ACCESS_TOKEN


Visualize notas de ordens

curl -X GET https://api.mercadolibre.com/orders/$ORDER_ID/notes?access_token=$ACCESS_TOKEN


Como alterar uma nota

curl -X PUT -H "Content-Type: application/json" -d '{
    "note": "test2",
}' https://api.mercadolibre.com/orders/$ORDER_ID/notes/$NOTE_ID?access_token=$ACCESS_TOKEN


Elimine notas

curl -X DELETE https://api.mercadolibre.com/orders/$ORDER_ID/notes/$NOTE_ID?access_token=$ACCESS_TOKEN


Bloquear ofertas

Embora estejam disponíveis uma prestação e fluxos de prevenção de fraude para manter a segurança de compradores e vendedores, em alguns casos, você pode encontrar usuários que, por algum motivo, ofertam nos anúncios. Estes casos podem ser enviados para a lista negra, a fim de evitar que voltem a ofertar.


Como bloqueio ofertas de um usuário específico?

Faça uma solicitação POST com o cust_id do usuário que você quer bloquear no JSON e o seu na url, como no exemplo a seguir:

curl -X POST -H "Content-Type: application/json" -d
{ user_id: {cust_id} }
https://api.mercadolibre.com/users/$CUST_ID/order_blacklist?access_token=$ACCESS_TOKEN


Consulte sua lista negra

Se você quiser saber quais são os usuários de sua lista negra, faça uma solicitação GET para a API com seu cust_id na url:

curl -X GET https://api.mercadolibre.com/users/$CUST_ID/order_blacklist?access_token=$ACCESS_TOKEN


Elimine um usuário de sua lista negra

Se você não quer continuar bloqueando um usuário para ele fazer ofertas, pode eliminá-lo de sua lista negra realizando uma solicitação DELETE para a API com seu cust_id e o cust_id do usuário.

curl -X DELETE https://api.mercadolibre.com/users/$YOUR_CUST_ID/order_blacklist/$CUST_ID


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 https://api.mercadolibre.com/orders/$ORDER_ID?access_token=$ACCESS_TOKEN

Resposta:
< 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",
  ],
}


Próximo: Mensagens de pós venda