Developers

Documentação do Mercado Shops

Confira todas as informações necessárias sobre as APIs Mercado Shops.

Documentação do

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