Documentação do Mercado Shops
Confira todas as informações necessárias sobre as APIs Mercado Shops.
Documentação do
Vendas de usuários convidados
Considerações
Os dados que pediremos ao usuário convidado, além do nome e sobrenome, será:
- MLM: e-mail
- MLB: e-mail + CPF o CNPJ
- MLA: e-mail + DNI
- MLC: e-mail + RUT
Os usuários convidados:
- Não contarão com compra protegida;
- não terão password e não poderão fazer login no Mercado Livre e no Mercado Pago;
- não contarão com o campo de mensagens nos fluxos do Mercado Livre;
- terão uma marca para ser identificado como tal, a mesma será lite e um ID.
Para este tipo de usuário criamos um tipo de sessão para autorizar o acesso apenas aos fluxos guest. Considerar que:
- Será criado um user por loja e e-mail por compra.
- As ventas destes usuários não afetam a reputação do vendedor.
Cada usuário convidado poderá realizar o seguimento de sua compra acessando a informação disponível em seu e-mail e poderá ver cada compra separadamente.
Casos em que o vendedor receberá um e-mail de uma compra guest:
Status | E-mail comprador | E-mail vendedor |
---|---|---|
PAGAMENTO RECUSADO | Sim | Não |
EM PROCESSO | Não | Não |
PACOTE EM PREPARAÇÃO | Não | Sim |
PACOTE EM PREPARAÇÃO ATRASADO | Não | Sim |
PACOTE A CAMINHO | Sim | Não |
PACOTE A CAMINHO ATRASADO | Sim | Sim |
PACOTE NO PONTO DE RETIRADA | Sim | Não |
PACOTE ENTREGUE | Sim | Não |
Identificar usuários convidados
Para saber se a order foi criada por um usuário convidado, deverá revisar o novo array context que terá informações detalhadas. Revise o campo flows, no array context, verificando que o valor é lite e channel corresponde ao mshops. Saiba mais acessando gerenciar orders.
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/$ORDER_ID
Exemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/2000003509333216
Resposta:
{
"id": 2000003509333216,
"date_created": "2022-04-28T09:25:08.000-04:00",
"date_closed": "2022-04-28T09:25:10.000-04:00",
"last_updated": "2022-04-28T09:27:11.000-04:00",
"manufacturing_ending_date": "2022-06-12T09:25:10.000-04:00",
"comment": null,
"pack_id": null,
"pickup_id": null,
"order_request": {
"return": null,
"change": null
},
"fulfilled": null,
"application_id": "3606760543142028",
"hidden_for_seller": false,
"buying_mode": "buy_equals_pay",
"shipping_cost": 1504.99,
"mediations": [],
"total_amount": 20000,
"paid_amount": 21504.99,
"coupon": {
"id": null,
"amount": 0
},
"expiration_date": "2022-07-10T09:25:10.000-04:00",
"order_items": [
{
"item": {
"id": "MLA924971996",
"title": "Maceta De Plastico (item De Prueba No Ofertar)",
"category_id": "MLA11034",
"variation_id": 87620137218,
"seller_custom_field": null,
"variation_attributes": [
{
"id": "COLOR",
"name": "Color",
"value_id": "52049",
"value_name": "Negro"
}
],
"warranty": "Sin garantía",
"condition": "new",
"seller_sku": null,
"global_price": null,
"net_weight": null
},
"quantity": 1,
"requested_quantity": {
"value": 1,
"measure": "unit"
},
"picked_quantity": null,
"unit_price": 20000,
"full_unit_price": 22000,
"currency_id": "ARS",
"manufacturing_days": 45,
"sale_fee": 3800,
"listing_type_id": "gold_pro",
"base_exchange_rate": null,
"base_currency_id": null,
"element_id": null,
"bundle": null,
"discounts": null
}
],
"currency_id": "ARS",
"payments": [
{
"id": 21926289045,
"order_id": 2000003509333216,
"payer_id": 1109579510,
"collector": {
"id": 660948237
},
"card_id": null,
"site_id": "MLA",
"reason": "Maceta De Plastico (item De Prueba No Ofertar)",
"payment_method_id": "visa",
"currency_id": "ARS",
"installments": 1,
"issuer_id": "1",
"atm_transfer_reference": {
"company_id": null,
"transaction_id": null
},
"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": 20000,
"transaction_amount_refunded": 0,
"taxes_amount": 0,
"shipping_cost": 1504.99,
"coupon_amount": 0,
"overpaid_amount": 0,
"total_paid_amount": 21504.99,
"installment_amount": 21504.99,
"deferred_period": null,
"date_approved": "2022-04-28T09:25:10.000-04:00",
"authorization_code": "301299",
"transaction_order_id": null,
"date_created": "2022-04-28T09:25:09.000-04:00",
"date_last_modified": "2022-04-28T09:25:26.000-04:00",
"marketplace_fee": 3800
}
],
"shipping": {
"id": 41336716357
},
"status": "paid",
"status_detail": null,
"tags": [
"mshops",
"not_delivered",
"test_order",
"paid"
],
"internal_tags": [],
"feedback": {
"buyer": null,
"seller": null
},
"context": {
"channel": "mshops",
"site": "MLA",
"flows": [
"lite"
]
},
"seller": {
"id": 660948237
},
"buyer": {
"id": 1109579510
},
"taxes": {
"amount": null,
"currency_id": null,
"id": null
}
}
O novo array:
"context": {
"channel": "mshops",
"site": "MLA",
"flows": [
"lite"
]
Parâmetros
channel: canais de vendas através dos quais a order foi gerada.
site: país onde a venda foi processada.
flows: é uma lista de características da origem da compra, a seguir tags atuais:
- cbt
- subscription
- contract
- supermarket
- 3x_campaign
- high_concurrency
- catalog
- lite (comprador convidado)
Verificar informação do usuário convidado
Poderá identificar as informações do comprador convidado através do recurso /users , ele terá um ID como qualquer outro usuário, a informação que diferencia o comprador convidado está no campo user_type: lite.
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$USER_ID
Exemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/1109579510
Resposta:
{
"id": 1109579510,
"nickname": "TEST_USER_1109579510",
"registration_date": "2022-04-19T16:01:57.099-04:00",
"country_id": "AR",
"address": {
"city": "Palermo",
"state": "AR-C"
},
"user_type": "lite",
"tags": [
"test_user",
"lite"
],
"logo": null,
"points": 0,
"site_id": "MLA",
"permalink": "http://perfil.mercadolibre.com.ar/TEST_USER_1109579510",
"seller_reputation": {
"level_id": null,
"power_seller_status": null,
"transactions": {
"canceled": 0,
"completed": 0,
"period": "historic",
"ratings": {
"negative": 0,
"neutral": 0,
"positive": 0
},
"total": 0
}
},
"buyer_reputation": {
"tags": null
},
"status": {
"site_status": "active"
}
}
Cancelamentos
Para estes tipos de vendas, o único que pode realizar o cancelamento de uma venda é o vendedor, e deverá fazer isso efetuando uma devolução de pagamento mediante um POST a /v1/payments/{id}/refunds. Saiba mais sobre como concretizar uma devolução fazendo um reembolso.
Chamada:
curl -X POST \
'https://api.mercadopago.com/v1/payments/{id}/refunds' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"amount": 5
}'
Exemplo:
curl --location --request POST 'https://api.mercadopago.com/v1/payments/23415342519/refunds' \
--header 'Authorization: Bearer APP_USR-2843871569852229-060217-cdc5b8cafba2c1dda4ffeb2235f79b4c-553421365' \
--header 'Content-Type: text/plain' \
--data-raw '{
"amount": 683397.27
}'
Resposta:
{
"id": 1150318715,
"payment_id": 23415342519,
"amount": 683397.27,
"metadata": {},
"source": {
"id": "553421365",
"name": "Nitienda Test Test",
"type": "collector"
},
"date_created": "2022-06-23T18:21:49.114-04:00",
"unique_sequence_number": null,
"refund_mode": "standard",
"adjustment_amount": 0,
"status": "approved",
"reason": null,
"labels": [],
"amount_refunded_to_payer": 683397.27,
"partition_details": []
}
Próxima: Campanhas com parcelamento.