Documentação do Mercado Shops

Confira todas as informações necessárias sobre as APIs Mercado Shops.
circulos azuis em degrade
Última atualização em 24/10/2023

Acesso aos dados do cliente

Importante:
- Para acessar essas APIs, tanto o vendedor quanto o integrador precisam atender a certos requisitos, devem controlar os erros que o recurso pode dar como resposta por não ter os requisitos exigidos.
- Para utilizar o recurso é necessário preencher o seguinte formulário, para ter acesso ao processo de certificação e atender aos requisitos.

Os vendedores do Mercado Shops precisam ter acesso aos dados de seus clientes para poder utilizá-los em campanhas de marketing ou visualizar de forma granular as vendas realizadas em um período.
Para isso, disponibilizamos as informações através dos seguintes recursos, a fim de melhorar a comunicação com seus compradores, fortalecer a experiência pós-venda e fidelizá-los.


Nota:
Se quiser saber mais sobre como trabalhar com as informações disponíveis nas vendas do vendedor, você pode encontrar mais informações em experiência de pós-venda.


Consultar por intervalos de datas

Importante:
Lembre-se que para consultar com datas, a consulta não considera minutos ou segundos, apenas intervalos de horas.

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/shops/cda/customers?order_created_from=$DATE_FROM&order_created_to=$DATE_TO

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/shops/cda/customers?order_created_from=2021-01-18T00:00:00.000-00:00&order_created_to=2022-01-18T00:00:00.000-00:00

Resposta:

'{
    "results": [
        {
            "id": 4749149808,
            "date_created": "2021-07-29T11:32:23.000+00:00",
            "paid_amount": 1150.0,
            "currency_id": "ARS",
            "buyer": {
                "id": 798779895,
                "person": {
                    "birthdate": "1981-06-18",
                    "first_name": "Buyer",
                    "gender": "F",
                    "last_name": "Blackburn 798779895"
                },
                "contact": {
                    "email": "sheree.blackburn+798779895@example.co.uk",
                    "phone": "54 1199351139 ext. 261"
                },
                "ms_seller_promotions": true
            },
            "order_items": [
                {
                    "item": {
                        "title": "Item De Testeo, Por Favor No Ofertar --kc:off"
                    }
                },
                {
                    "item": {
                        "title": "Item De Testeo 2, Por Favor No Ofertar --kc:off"
                    }
                }
            ],
            "coupon": {
                "id": null,
                "amount": 0.0
            }
        },
        {
            "id": 4697463433,
            "date_created": "2021-07-07T15:41:55.000+00:00",
            "paid_amount": 1494.99,
            "currency_id": "ARS",
            "buyer": {
                "id": 780777832,
                "person": null,
                "contact": {
                    "email": "sheree.blackburn+780777832@example.co.uk",
                    "phone": "54 1199351139"
                },
                "ms_seller_promotions": false
            },
            "order_items": [
                {
                    "item": {
                        "title": "Item De Testeo, Por Favor No Ofertar --kc:off"
                    }
                }
            ],
            "coupon": {
                "id": null,
                "amount": 0.0
            }
        },
        {
            "id": 4697450495,
            "date_created": "2021-07-07T15:38:08.000+00:00",
            "paid_amount": 1500.0,
            "currency_id": "ARS",
            "buyer": {
                "id": 780777832,
                "person": {
                    "birthdate": "1981-06-18",
                    "first_name": "Buyer",
                    "gender": "F",
                    "last_name": "Blackburn 780777832"
                },
                "contact": {
                    "email": "sheree.blackburn+780777832@example.co.uk",
                    "phone": "541199351139"
                },
                "ms_seller_promotions": true
            },
            "order_items": [
                {
                    "item": {
                        "title": "Sticker Tarjetas"
                    }
                }
            ],
            "coupon": {
                "id": null,
                "amount": 0.0
            }
        },
        {
            "id": 4647686563,
            "date_created": "2021-06-16T17:26:41.000+00:00",
            "paid_amount": 2004.99,
            "currency_id": "ARS",
            "buyer": {
                "id": 656454498,
                "person": {
                    "birthdate": "1981-01-12",
                    "first_name": "Mark",
                    "gender": "M",
                    "last_name": "Blackburn 656454498"
                },
                "contact": {
                    "email": "mark.blackburn+656454498@example.co.uk",
                    "phone": null
                },
                "ms_seller_promotions": false
            },
            "order_items": [
                {
                    "item": {
                        "title": "Billetera Ideal Para Gente Como Vos!"
                    }
                }
            ],
            "coupon": {
                "id": null,
                "amount": 0.0
            }
        }
    ],
    "paging": {
        "total": 4,
        "limit": 15,
        "scroll_id": "YXBpY29yZS1vcmlnaW5hbC1vcmRlcnM=:ZHMtYXBpY29yZS1vcmlnaW5hbC1vcmRlcnMtMDM=:FGluY2x1ZGVfY29udGV4dF91dWlkDXF1ZXJ5QW5kRmV0Y2gBFEs1djliWDRCdW1sSjF0ZENGS3l0AAAAAHPJOh0WRUlRNGJVc3FTUWk5ZUtLN0NEM2NDQQ=="
    }
}'

Consultar por scroll id

Já feita a primeira consulta por intervalos de datas obtendo o scroll_id correspondente, pode ser consultada com o valor recebido. Você deve continuar com os seguintes recursos:

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/shops/cda/customers?scroll_id=$SCROLL_ID

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/shops/cda/customers?scroll_id=YXBpY29yZS1vcmlnaW5hbC1vcmRlcnM=:ZHMtYXBpY29yZS1vcmlnaW5hbC1vcmRlcnMtMDM=:FGluY2x1ZGVfY29udGV4dF91dWlkDXF1ZXJ5QW5kRmV0Y2gBFEs1djliWDRCdW1sSjF0ZENGS3l0AAAAAHPJOh0WRUlRNGJVc3FTUWk5ZUtLN0NEM2NDQQ==

Resposta com a lista de compradores e suas informações

'{
    "results": [
        {
            "id": 4749149808,
            "date_created": "2021-07-29T11:32:23.000+00:00",
            "paid_amount": 1150.0,
            "currency_id": "ARS",
            "buyer": {
                "id": 798779895,
                "person": {
                    "birthdate": "1981-06-18",
                    "first_name": "Buyer",
                    "gender": "F",
                    "last_name": "Blackburn 798779895"
                },
                "contact": {
                    "email": "sheree.blackburn+798779895@example.co.uk",
                    "phone": "54 1199351139 ext. 261"
                },
                "ms_seller_promotions": true
            },
            "order_items": [
                {
                    "item": {
                        "title": "Item De Testeo, Por Favor No Ofertar --kc:off"
                    }
                },
                {
                    "item": {
                        "title": "Item De Testeo 2, Por Favor No Ofertar --kc:off"
                    }
                }
            ],
            "coupon": {
                "id": null,
                "amount": 0.0
            }
        },
        {
            "id": 4697463433,
            "date_created": "2021-07-07T15:41:55.000+00:00",
            "paid_amount": 1494.99,
            "currency_id": "ARS",
            "buyer": {
                "id": 780777832,
                "person": null,
                "contact": {
                    "email": "sheree.blackburn+780777832@example.co.uk",
                    "phone": "54 1199351139"
                },
                "ms_seller_promotions": false
            },
            "order_items": [
                {
                    "item": {
                        "title": "Item De Testeo, Por Favor No Ofertar --kc:off"
                    }
                }
            ],
            "coupon": {
                "id": null,
                "amount": 0.0
            }
        },
        {
            "id": 4697450495,
            "date_created": "2021-07-07T15:38:08.000+00:00",
            "paid_amount": 1500.0,
            "currency_id": "ARS",
            "buyer": {
                "id": 780777832,
                "person": {
                    "birthdate": "1981-06-18",
                    "first_name": "Buyer",
                    "gender": "F",
                    "last_name": "Blackburn 780777832"
                },
                "contact": {
                    "email": "sheree.blackburn+780777832@example.co.uk",
                    "phone": "541199351139"
                },
                "ms_seller_promotions": true
            },
            "order_items": [
                {
                    "item": {
                        "title": "Sticker Tarjetas"
                    }
                }
            ],
            "coupon": {
                "id": null,
                "amount": 0.0
            }
        },
        {
            "id": 4647686563,
            "date_created": "2021-06-16T17:26:41.000+00:00",
            "paid_amount": 2004.99,
            "currency_id": "ARS",
            "buyer": {
                "id": 656454498,
                "person": {
                    "birthdate": "1981-01-12",
                    "first_name": "Mark",
                    "gender": "M",
                    "last_name": "Blackburn 656454498"
                },
                "contact": {
                    "email": "mark.blackburn+656454498@example.co.uk",
                    "phone": null
                },
                "ms_seller_promotions": false
            },
            "order_items": [
                {
                    "item": {
                        "title": "Billetera Ideal Para Gente Como Vos!"
                    }
                }
            ],
            "coupon": {
                "id": null,
                "amount": 0.0
            }
        }
    ],
    "paging": {
        "total": 4,
        "limit": 15,
        "scroll_id": "YXBpY29yZS1vcmlnaW5hbC1vcmRlcnM=:ZHMtYXBpY29yZS1vcmlnaW5hbC1vcmRlcnMtMDM=:FGluY2x1ZGVfY29udGV4dF91dWlkDXF1ZXJ5QW5kRmV0Y2gBFEs1djliWDRCdW1sSjF0ZENGS3l0AAAAAHPJOh0WRUlRNGJVc3FTUWk5ZUtLN0NEM2NDQQ=="
    }
}'

Consultar por buyer_id

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/shops/cda/customers?buyer_id=$BUYER_ID

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/shops/cda/customers?buyer_id=1080426219

Resposta com as orders que o comprador registrou e suas informações.

{
    "results": [
        {
            "id": 2000005004071824,
            "date_created": "2023-01-26T21:27:24.000+00:00",
            "buyer": {
                "id": 1080426219,
                "person": {
                    "birthdate": "1987-05-26",
                    "first_name": "Faulkner",
                    "gender": "M",
                    "last_name": "Hoover"
                },
                "contact": {
                    "phone": "542661180352832",
                    "email": "faulkner.hoover@example.net"
                },
                "ms_seller_promotions": false
            },
            "order_items": [
                {
                    "item": {
                        "title": "Item De Testeo, Por Favor No Ofertar --kc:off",
                        "id": "MLA897945718"
                    }
                }
            ],
            "paid_amount": 1150.0,
            "currency_id": "ARS",
            "coupon": {
                "id": null,
                "amount": 0.0
            }
        },
        {
            "id": 2000005003466456,
            "date_created": "2023-01-26T19:44:18.000+00:00",
            "buyer": {
                "id": 1080426219,
                "person": {
                    "birthdate": "1987-05-26",
                    "first_name": "Faulkner",
                    "gender": "M",
                    "last_name": "Hoover"
                },
                "contact": {
                    "phone": "542661180352832",
                    "email": "faulkner.hoover@example.net"
                },
                "ms_seller_promotions": false
            },
            "order_items": [
                {
                    "item": {
                        "title": "Peluche De Stitch",
                        "id": "MLA932413098"
                    }
                }
            ],
            "paid_amount": 1974.99,
            "currency_id": "ARS",
            "coupon": {
                "id": null,
                "amount": 0.0
            }
        },
        {
            "id": 2000005003174726,
            "date_created": "2023-01-26T18:58:33.000+00:00",
            "buyer": {
                "id": 1080426219,
                "person": {
                    "birthdate": "1987-05-26",
                    "first_name": "Faulkner",
                    "gender": "M",
                    "last_name": "Hoover"
                },
                "contact": {
                    "phone": "542661180352832",
                    "email": "faulkner.hoover@example.net"
                },
                "ms_seller_promotions": false
            },
            "order_items": [
                {
                    "item": {
                        "title": "Item De Testeo, Por Favor No Ofertar --kc:off",
                        "id": "MLA897945718"
                    }
                }
            ],
            "paid_amount": 1150.0,
            "currency_id": "ARS",
            "coupon": {
                "id": null,
                "amount": 0.0
            }
        },
        {
            "id": 2000005002534814,
            "date_created": "2023-01-26T17:21:16.000+00:00",
            "buyer": {
                "id": 1080426219,
                "person": {
                    "birthdate": "1987-05-26",
                    "first_name": "Faulkner",
                    "gender": "M",
                    "last_name": "Hoover"
                },
                "contact": {
                    "phone": "542661180352832",
                    "email": "faulkner.hoover@example.net"
                },
                "ms_seller_promotions": false
            },
            "order_items": [
                {
                    "item": {
                        "title": "Pilas",
                        "id": "MLA930546840"
                    }
                }
            ],
            "paid_amount": 3400.0,
            "currency_id": "ARS",
            "coupon": {
                "id": null,
                "amount": 0.0
            }
        },
        {
            "id": 5289783151,
            "date_created": "2022-02-25T14:11:04.000+00:00",
            "buyer": {
                "id": 1080426219,
                "person": {
                    "birthdate": "1987-05-26",
                    "first_name": "Faulkner",
                    "gender": "M",
                    "last_name": "Hoover"
                },
                "contact": {
                    "phone": "542661180352832",
                    "email": "faulkner.hoover@example.net"
                },
                "ms_seller_promotions": false
            },
            "order_items": [
                {
                    "item": {
                        "title": "Sticker Tarjetas",
                        "id": "MLA897947944"
                    }
                }
            ],
            "paid_amount": 1500.0,
            "currency_id": "ARS",
            "coupon": {
                "id": null,
                "amount": 0.0
            }
        }
    ],
    "paging": {
        "total": 5,
        "limit": 5,
        "scroll_id": "YXBpY29yZS1vcmlnaW5hbC1vcmRlcnM=:ZHMtYXBpY29yZS1taXJyb3ItMDY=:FGluY2x1ZGVfY29udGV4dF91dWlkDXF1ZXJ5QW5kRmV0Y2gBFEFtWDVQSVlCX0pCUHQ4ckpfYXBCAAAAABfg_NMWbE5JZEVULVRUbGl1Mk9jYW1pZ0Y1UQ=="
    }
}

Consultar por order_id

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/shops/cda/customers?order_id=$ORDER_ID

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/shops/cda/customers?order_id=2000005003466456

Resposta com a order pesquisada e suas informações.

{
    "results": [
        {
            "id": 2000005003466456,
            "date_created": "2023-01-26T19:44:18.000+00:00",
            "buyer": {
                "id": 1080426219,
                "person": {
                    "birthdate": "1987-05-26",
                    "first_name": "Faulkner",
                    "gender": "M",
                    "last_name": "Hoover"
                },
                "contact": {
                    "phone": "542661180352832",
                    "email": "faulkner.hoover@example.net"
                },
                "ms_seller_promotions": false
            },
            "order_items": [
                {
                    "item": {
                        "title": "Peluche De Stitch",
                        "id": "MLA932413098"
                    }
                }
            ],
            "paid_amount": 1974.99,
            "currency_id": "ARS",
            "coupon": {
                "id": null,
                "amount": 0.0
            }
        }
    ],
    "paging": {
        "total": 1,
        "limit": 1,
        "scroll_id": "YXBpY29yZS1vcmlnaW5hbC1vcmRlcnM=:ZHMtYXBpY29yZS1vcmlnaW5hbC1vcmRlcnMtMDM=:FGluY2x1ZGVfY29udGV4dF91dWlkDXF1ZXJ5QW5kRmV0Y2gBFGxCVDBQSVlCcXNsaC1IVHFaal9wAAAAAMNKjsAWQVlMWk9VLTRUUENHelJRWUg0dHRWdw=="
    }
}

Glossário

Parâmetros do pedido

Campos Descrição de campo Possíveis valores para o campo e sua descrição
order_created_from Data inicial e final da pesquisa. Compare com a data de criação dos pedidos. Deve estar no formato ISO-8601. 2021-01-18T00:00:00.000-00:00.
order_created_to Data inicial e final da pesquisa. Compare com a data de criação dos pedidos. Deve estar no formato ISO-8601. 2022-01-18T00:00:00.000-00:00.
scroll_id Usado para continuar a paginação da pesquisa. YXBpY29yZS1vcmlnaW5hb
C1vcmRlcnM=:ZHMtYXBpY
29yZS1vcmlnaW5hbC1vcm
RlcnMtMDM=:FGluY2x1ZG
VfY29udGV4dF91dWlkDXF
1ZXJ5QW5kRmV0Y2gBFEs1
djliWDRCdW1sSjF0ZENGS
3l0AAAAAHPJOh0WRUlRNG
JVc3FTUWk5ZUtLN0NEM2N
DQQ==
buyer_id É utilizado para buscar informações filtrando pelo ID do comprador. 1080426219
order_id É usado para filtrar por uma order específica. 2000005003466456

Parâmetros de resposta

Campos Descrição de campo Possíveis valores para o campo e sua descrição
results Lista de orders. [ ] , [order], [order, order, …]
paging Informações de paginação da busca. Paging [ total, limit, scroll_id]

Order

Campos Descrição de campo Possíveis valores para o campo e sua descrição
id ID de order. order_id.
date_created Data e hora de criação da order. Data e hora expressas conforme ISO 8601 ex. 2021-06-16T17:26:41.000+00:00
paid_amount Valor pago pelo comprador na order. value.
currency_id Tipo de moeda em que o pagamento foi feito. Valor conforme ISO 4217 da moeda, ex. COP, MXN, ARS, CLP, BRL.
buyer Comprador da order. buyer.
order_items Lista de itens comprados. [ ], [orderItem], [order_Item, orderItem, …]
coupon Informações do cupom usado na order (se aplicável). coupon.

Buyer

Campos Descrição de campo Possíveis valores para o campo e sua descrição
id ID do comprador. ID do comprador.
person As informações do comprador podem ser null. person.
contact Informações de contato do comprador. contact.
ms_seller_promotions Aceitação por parte do comprador em receber informação promocional através dos seus dados de contacto. true: o comprador concorda em receber as informações promocionais.
false: o comprador não aceita receber informações promocionais.

Person

Campos Descrição de campo Possíveis valores para o campo e sua descrição
birthday Aniversário do comprador. Pode não apresentar. Ex. 1999-01-20 formato YYYY-MM-DD
first_name Nome do comprador.
last_name Sobrenome do comprador.
gender Gênero registrado para o comprador de acordo com seu documento de identidade. Pode não ser apresentado. F: femenino.
M: masculino.

Contact

Campos Descrição de campo Possíveis valores para o campo e sua descrição
email E-mail do comprador.
phone Telefone do comprador.

Coupon

Campos Descrição de campo Possíveis valores para o campo e sua descrição
id ID do cupom. Se chegar null, significa que nenhum cupom foi aplicado na compra.
amount Desconto aplicado na compra com o cupom.

OrderItem

Campos Descrição de campo Possíveis valores para o campo e sua descrição
Item Informação do item. Item.

Ítem

Campos Descrição de campo Possíveis valores para o campo e sua descrição
Title Título da publicação do item.
Id ID do item.

Paging

Campos Descrição de campo Possíveis valores para o campo e sua descrição
total Total de orders resultantes da busca.
limit Número máximo de orders apresentadas por página.
scroll_id ID de scroll da busca. Para continuar a busca se deve enviar este valor como parâmetro na seguinte consulta, sempre usar o último gerado.

Errores

Status_Code Código de error Mensagem de erro Descrição Possível solução
400 bad request O intervalo de datas deve ser enviado. O integrador deve enviar o intervalo de datas para realizar a petição.
401 unauthorized Seller has pending to ask their identity validation O vendedor não validou sua identidade. O vendedor que está sendo associado deve acessar o painel de Mshops, entrar na seção de clientes e culminar o fluxo de validações. Mais informação em nosso devsite.
401 unauthorized Signature not found by user_id and checkpoint_id Vendedor não assinou os termos e condições O vendedor que está sendo associado deve acessar o painel de Mshops, entrar na seção de clientes e culminar o fluxo de validações. Mais informação em nosso devsite.
401 unauthorized Client.id not allowed to continue operation O client_id não conta com as permissões para acessar a informação do vendedor. A funcionalidade é exclusiva a partners selecionados.
401 unauthorized invalid_token Verificar el access_token.
403 forbidden ACCESS_TOKEN_NOT_GRANTED Não tem permissão para realizar a consulta Verificar que tenha permissão através do integrador de consultar esta API
404 not_found There is no more info associated with this scroll_id O vendedor não conta com mais vendas associadas ao scroll_id dado. Ou seja, a paginação finalizou.
429 too_many_requests Over quota Foram feitos muitos requests em um período curto de tempo
500 internal_server_error Trata-se de um erro esperado em qualquer passo do fluxo. Entre em contato conosco para determinar qual foi a causa.