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 22/10/2024

Acesso a dados do cliente

Os vendedores do Mercado Shops precisam de acesso aos dados dos seus clientes, assinantes e carrinhos abandonados para utilizá-los em campanhas de marketing ou para visualizar as vendas de forma detalhada em um período determinado.

Por isso, disponibilizamos essas informações através de vários recursos, com o objetivo de melhorar a comunicação com os compradores, otimizar a experiência pós-venda e fortalecer sua fidelidade.

Importante:

Para acessar esses recursos, é necessário completar o seguinte formulário para iniciar o processo de certificação e cumprir os requisitos.

Além disso, tenha em mente que para utilizar a nova versão, você deve incluir no header: App-Version: 2.

Por fim, lembre-se que o vendedor deve acessar a seção "Clientes" dentro do Mercado Shops e aceitar os Termos e Condições.

Consultar por intervalos de datas

Importante:

Ao realizar consultas com datas, o sistema não considera minutos ou segundos, apenas intervalos de horas.

Temos as seguintes limitações nos períodos de consulta:

Assinantes: Disponíveis desde janeiro de 2023.
Pedidos: Disponíveis desde 25 de setembro de 2023.
Carrinhos: Disponíveis desde agosto de 2023.

A partir de agosto de 2023, os dados com mais de 1 ano e meio serão depurados.

Com o seguinte recurso, você poderá consultar os dados de clientes de todos os "tipos", incluindo pedidos, assinantes e carrinhos abandonados, dentro de um intervalo de datas específico.

Parâmetros:

Campos	Descrição do campo	Valores possíveis para o campo e sua descrição
order_created_from	Data de início da busca. Compara com a data de criação das ordens. Deve estar no formato ISO-8601.	2021-01-18T00:00:00.000-00:00
order_created_to	Data de fim da busca. Compara com a data de criação das ordens. Deve estar no formato ISO-8601.	2022-01-18T00:00:00.000-00:00

Resposta:

'{
  "results": [
    {
      "id": 4749149808,
      "type": "order",
      "date_created": "2021-07-29T11:32:23.000+00:00",
      "amount": 1150.0,
      "currency_id": "ARS",
      "buyer": {
        "id": 798779894,
        "person": {
          "birthdate": "06-18",
          "first_name": "Buyer",
          "gender": "M",
          "last_name": "Bla 798779894"
        },
        "contact": {
          "email": "sheree.blackburn+798779895@example.co.uk",
          "phone": "54 1199351139 ext. 261",
          "state": "Capital Federal",
          "city": "Palermo"
        },
        "ms_seller_promotions": false,
        "subscriber": false
      },
      "items": [
        {
          "item": {
            "id": 1,
            "title": "Item De Testeo, Por Favor No Ofertar --kc:off",
            "quantity": 1
          }
        },
        {
          "item": {
            "id": 2,
            "title": "Item De Testeo 2, Por Favor No Ofertar --kc:off",
            "quantity": 2
          }
        }
      ],
      "coupon": {
        "id": null,
        "amount": 0.0
      }
    },
    {
      "id": 449808,
      "type": "abandoned_cart",
      "date_created": "2021-07-29T11:32:23.000+00:00",
      "buyer": {
        "id": 798779895,
        "person": {
          "birthdate": "06-18",
          "first_name": "Buyer",
          "gender": "F",
          "last_name": "Blackburn 798779895"
        },
        "contact": {
          "email": "sheree.blackburn+798779895@example.co.uk",
          "phone": "54 1199351139 ext. 261",
          "state": "Capital Federal",
          "city": "Palermo"
        },
        "ms_seller_promotions": true,
        "subscriber": true
      },
      "items": [
        {
          "item": {
            "id": 1,
            "title": "Item De Testeo, Por Favor No Ofertar --kc:off",
            "quantity": 2
          }
        },
        {
          "item": {
            "id": 2,
            "title": "Item De Testeo 2, Por Favor No Ofertar --kc:off",
            "quantity": 2
          }
        }
      ]
    },
    {
      "id": 52,
      "type": "subscriber",
      "date_created": "2021-07-29T11:32:23.000+00:00",
      "follower": {
        "id": 798779895,
        "person": {
          "birthdate": "06-18",
          "first_name": "Buyer",
          "gender": "F",
          "last_name": "Blackburn 798779895"
        },
        "contact": {
          "email": "sheree.blackburn+798779895@example.co.uk",
          "phone": "54 1199351139 ext. 261",
          "state": "Capital Federal",
          "city": "Palermo"
        },
        "ms_seller_promotions": true,
        "buyer": true
      }
    },
    {
      "id": 54,
      "type": "subscriber",
      "date_created": "2024-06-29T11:32:23.000+00:00",
      "follower": {
        "id": 798779898,
        "contact": {
          "email": "sheree.blackburn+798779895@example.co.uk"
        },
        "ms_seller_promotions": true,
        "buyer": false
      }
    }
  ],
  "paging": {
    "total": 4,
    "limit": 15,
    "scroll_id": "YXBpY29yZS1vcmlnaW5hbC1vcmRlcnM=:ZHMtYXBpY29yZS1vcmlnaW5hbC1vcmRlcnMtMDM=:FGluY2x1ZGVfY29udGV4dF91dWlkDXF1ZXJ5QW5kRmV0Y2gBFEs1djliWDRCdW1sSjF0ZENGS3l0AAAAAHPJOh0WRUlRNGJVc3FTUWk5ZUtLN0NEM2NDQQ=="
  }
}'

Campos de resposta

A resposta de um GET ao recurso CDA/customers?order_created_from&order_created_to fornecerá os seguintes parâmetros:

id: id do tipo
type: tipo de documento [order, subscriber, abandoned_cart]
date_created: Data e hora da criação do pedido
- Data e hora expressa conforme ISO 8601 ex. 2021-06-16T17:26:41.000+00:00
amount: Valor pago pelo comprador no pedido, não enviado no carrinho.
- value
currency_id: Tipo de moeda na qual o pagamento foi realizado
- Valor de acordo com o ISO 4217 da moeda, ex. COP, MXN, ARS, CLP, BRL
buyer: Comprador do pedido
- id: Id do comprador
person:
- birthday: Data de aniversário do comprador. Pode não ser exibido.
- 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 exibido.
  - “F”: feminino
  - “M”: masculino
contact:
- email: Email do comprador
- phone: Telefone do comprador
- state: Estado onde o endereço está localizado
- city: Cidade onde o endereço está localizado
ms_seller_promotions: Aceitação do comprador de receber informações promocionais por meio de seus dados de contato.
- “true”: o comprador aceita receber informações promocionais
- “false”: o comprador não aceita receber informações promocionais
subscriber: indicador se o comprador também é um follower
- true, false
items: Lista de itens comprados. Para os tipos abandoned_cart e order.
- Item: Informações do item.
- Title: Título da publicação do item.
- quantity: quantidade de itens no pedido ou carrinho abandonado.
coupon: Informações do cupom usado no pedido (se aplicável)
- id: Id do cupom (Se null, significa que nenhum cupom foi usado na compra.)
- amount: Desconto aplicado na compra com o cupom.
follower: Apenas para subscriber
- id: Id do assinante
- person: Informações do comprador, pode ser null.
- contact: Informações de contato do comprador
- ms_seller_promotions: Aceitação do comprador para receber informações promocionais
  - “true”: o comprador aceita receber informações promocionais
- buyer: Indicador se o assinante já fez uma compra.
  - true, false
Paging:
- total: Total de pedidos resultantes da pesquisa.
- limit: Número máximo de pedidos apresentados por página.
scroll_id: Usado para continuar a paginação da pesquisa.

Consultar por scroll id

Após realizar a primeira consulta por intervalos de datas, você receberá um scroll_id. Este valor permitirá realizar consultas adicionais para continuar acessando mais dados de maneira eficiente.

Parâmetros:

Campos	Descrição do campo	Valores possíveis para o campo e sua descrição
scroll_id	Usado para continuar a paginação da pesquisa.	YXBpY29yZS1vcm1naW5hbC1vcmluRc1nMtMDM=:ZMHtYXBpY29yZS1vcm1naW5hbC1vcmRlc1nMtMDM=:FGluY2x1ZGViY29udGV4dF91dWlkDXF1ZXJ5QW5kRmVoY29gBFEs1djl1WDRCdW1sSjF0ZENGS3l0AAA...

Chamada:

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

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'App-Version: 2' https://api.mercadolibre.com/shops/cda/customers?scroll_id=YXBpY29yZS1vcm1naW5hbC1vcm1naW5hbRc1nMtMDM=:FGluY2x1ZGViY29udGV4dF91dWlkDXF1ZXJ5QW5kRmVoY29...

Resposta:

'{
  "results": [
    {
      "id": 449809,
      "type": "abandoned_cart",
      "date_created": "2021-07-29T11:32:23.000+00:00",
      "buyer": {
        "id": 798779895,
        "person": {
          "birthdate": "06-18",
          "first_name": "Buyer",
          "gender": "F",
          "last_name": "Blackburn 798779895"
        },
        "contact": {
          "email": "sheree.blackburn+798779895@example.co.uk",
          "phone": "54 1199351139 ext. 261",
          "state": "Capital Federal",
          "city": "Palermo"
        },
        "ms_seller_promotions": true,
        "subscriber": true
      },
      "items": [
        {
          "item": {
            "id": 1,
            "title": "Item De Testeo, Por Favor No Ofertar --kc:off",
            "quantity": 2
          }
        },
        {
          "item": {
            "id": 2,
            "title": "Item De Testeo 2, Por Favor No Ofertar --kc:off",
            "quantity": 2
          }
        }
      ]
    },
    {
      "id": 56,
      "type": "subscriber",
      "date_created": "2024-06-29T11:32:23.000+00:00",
      "follower": {
        "id": 798779898,
        "contact": {
          "email": "sheree.blackburn+798779895@example.co.uk"
        },
        "ms_seller_promotions": true,
        "buyer": false
      }
    }
  ],
  "paging": {
    "total": 2,
    "limit": 15,
    "scroll_id": "YXBpY29yZS1vcmlnaW5hbC1vcmRlcnM=:ZHMtYXBpY29yZS1vcmlnaW5hbC1vcmRlcnMtMDM=:FGluY2x1ZGVfY29udGV4dF91dWlkDXF1ZXJ5QW5kRmV0Y2gBFEs1djliWDRCdW1sSjF0ZENGS3l0AAAAAHPJOh0WRUlRNGJVc3FTUWk5ZUtLN0NEM2NDQQ=="
  }
}'

Consultar por buyer_id

Este recurso permite obter as informações completas do comprador, incluindo seus pedidos e, se aplicável, informações sobre qualquer carrinho abandonado.

Parâmetros:

Campos	Descrição do campo	Valores possíveis para o campo e sua descrição
buyer_id	É usado para buscar informações filtrando pelo ID do comprador.	1080426219

Chamada:

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

Exemplo:

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

Resposta:

'{
  "results": [
    {
      "id": 4749149808,
      "type": "order",
      "date_created": "2021-07-29T11:32:23.000+00:00",
      "amount": 1150.0,
      "currency_id": "ARS",
      "buyer": {
        "id": 798779894,
        "person": {
          "birthdate": "06-18",
          "first_name": "Buyer",
          "gender": "M",
          "last_name": "Bla 798779894"
        },
        "contact": {
          "email": "sheree.blackburn+798779895@example.co.uk",
          "phone": "54 1199351139 ext. 261",
          "state": "Capital Federal",
          "city": "Palermo"
        },
        "ms_seller_promotions": false,
        "subscriber": false
      },
      "items": [
        {
          "item": {
            "id": 1,
            "title": "Item De Testeo, Por Favor No Ofertar --kc:off",
            "quantity": 1
          }
        },
        {
          "item": {
            "id": 2,
            "title": "Item De Testeo 2, Por Favor No Ofertar --kc:off",
            "quantity": 2
          }
        }
      ],
      "coupon": {
        "id": null,
        "amount": 0.0
      }
    },
    {
      "id": 349808,
      "type": "abandoned_cart",
      "date_created": "2021-07-29T11:32:23.000+00:00",
      "amount": 1150.0,
      "currency_id": "ARS",
      "buyer": {
        "id": 798779894,
        "person": {
          "birthdate": "06-18",
          "first_name": "Buyer",
          "gender": "F",
          "last_name": "Blackburn 798779895"
        },
        "contact": {
          "email": "sheree.blackburn+798779895@example.co.uk",
          "phone": "54 1199351139 ext. 261",
          "state": "Capital Federal",
          "city": "Palermo"
        },
        "ms_seller_promotions": true,
        "subscriber": true
      },
      "items": [
        {
          "item": {
            "id": 1,
            "title": "Item De Testeo, Por Favor No Ofertar --kc:off",
            "quantity": 2
          }
        },
        {
          "item": {
            "id": 2,
            "title": "Item De Testeo 2, Por Favor No Ofertar --kc:off",
            "quantity": 2
          }
        }
      ]
    }
  ],
  "paging": {
    "total": 2,
    "limit": 15,
    "scroll_id": "YXBpY29yZS1vcmlnaW5hbC1vcmRlcnM=:ZHMtYXBpY29yZS1vcmlnaW5hbC1vcmRlcnMtMDM=:FGluY2x1ZGVfY29udGV4dF91dWlkDXF1ZXJ5QW5kRmV0Y2gBFEs1djliWDRCdW1sSjF0ZENGS3l0AAAAAHPJOh0WRUlRNGJVc3FTUWk5ZUtLN0NEM2NDQQ=="
  }
}'

Consulta por order_id

Com este recurso, você poderá obter informações detalhadas sobre o comprador associado a um pedido específico usando o order_id. A resposta incluirá:

Dados do comprador, como seu status de assinatura.
Detalhes do pedido, incluindo informações sobre cupons aplicados.

Parâmetros:

Campos	Descrição do campo	Valores possíveis para o campo e sua descrição
order_id	Usado para filtrar por um pedido específico.	2000005003466456

Chamada:

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

Exemplo:

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

Resposta:

{
  "results": [
    {
      "id": 4749149808,
      "type": "order",
      "date_created": "2021-07-29T11:32:23.000+00:00",
      "amount": 1150.0,
      "currency_id": "ARS",
      "buyer": {
        "id": 798779894,
        "person": {
          "birthdate": "06-18",
          "first_name": "Buyer",
          "gender": "M",
          "last_name": "Bla 798779894"
        },
        "contact": {
          "email": "sheree.blackburn+798779895@example.co.uk",
          "phone": "54 1199351139 ext. 261",
          "state": "Capital Federal",
          "city": "Palermo"
        },
        "ms_seller_promotions": false,
        "subscriber": false
      },
      "items": [
        {
          "item": {
            "id": 1,
            "title": "Item De Testeo, Por Favor No Ofertar --kc:off",
            "quantity": 1
          }
        },
        {
          "item": {
            "id": 2,
            "title": "Item De Testeo 2, Por Favor No Ofertar --kc:off",
            "quantity": 2
          }
        }
      ],
      "coupon": {
        "id": null,
        "amount": 0.0
      }
    }
  ],
  "paging": {
    "total": 1,
    "limit": 1,
    "scroll_id": "YXBpY29yZS1vcmlnaW5hbC1vcmRlcnM=:ZHMtYXBpY29yZS1vcmlnaW5hbC1vcmRlcnMtMDM=:FGluY2x1ZGVfY29udGV4dF91dWlkDXF1ZXJ5QW5kRmV0Y2gBFEs1djliWDRCdW1sSjF0ZENGS3l0AAAAAHPJOh0WRUlRNGJVc3FTUWk5ZUtLN0NEM2NDQQ=="
  }
}

Consulta por type e intervalo de datas

Este recurso permitirá consultar dados de compradores e assinantes, filtrando por type (tipo de documento) e dentro de um intervalo de datas específico.

Parâmetros:

Campos	Descrição do campo	Valores possíveis para o campo e sua descrição
type	tipo de documento a buscar.	[order, subscriber, abandoned_cart]

Chamada:

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

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'App-Version: 2' https://api.mercadolibre.com/shops/cda/customers?order_created_from=2024-07-18T00:00:00.000-00:00&order_created_to=2024-07-29T00:00:00.000-00:00&type=order

Resposta:

{
  "results": [
    {
      "id": 4749149808,
      "type": "order",
      "date_created": "2024-07-29T11:32:23.000+00:00",
      "amount": 1150.0,
      "currency_id": "ARS",
      "buyer": {
        "id": 798779894,
        "person": {
          "birthdate": "06-18",
          "first_name": "Buyer",
          "gender": "M",
          "last_name": "Bla 798779894"
        },
        "contact": {
          "email": "sheree.blackburn+798779895@example.co.uk",
          "phone": "54 1199351139 ext. 261",
          "state": "Capital Federal",
          "city": "Palermo"
        },
        "ms_seller_promotions": false,
        "subscriber": false
      },
      "items": [
        {
          "item": {
            "id": 1,
            "title": "Item De Testeo, Por Favor No Ofertar --kc:off",
            "quantity": 1
          }
        },
        {
          "item": {
            "id": 2,
            "title": "Item De Testeo 2, Por Favor No Ofertar --kc:off",
            "quantity": 2
          }
        }
      ],
      "coupon": {
        "id": null,
        "amount": 0.0
      }
    }
  ],
  "paging": {
    "total": 1,
    "limit": 1,
    "scroll_id": "YXBpY29yZS1vcmlnaW5hbC1vcmRlcnM=:ZHMtYXBpY29yZS1vcmlnaW5hbC1vcmRlcnMtMDM=:FGluY2x1ZGVfY29udGV4dF91dWlkDXF1ZXJ5QW5kRmV0Y2gBFEs1djliWDRCdW1sSjF0ZENGS3l0AAAAAHPJOh0WRUlRNGJVc3FTUWk5ZUtLN0NEM2NDQQ=="
  }
}

Possíveis erros

O intervalo de datas deve ser enviado: O integrador deve enviar o intervalo de datas para poder realizar a solicitação.

{
    "error": "bad request",
    "status": 400,
    "cause": []
}

O vendedor não validou sua identidade. O vendedor ao qual está se associando deve acessar o painel do Mshops, entrar na seção de clientes e finalizar o fluxo de validações. Mais informações em nosso devsite.

{
    "message": "Seller has pending to ask their identity validation",
    "error": "unauthorized",
    "status": 401,
    "cause": []
}

O vendedor não assinou os termos e condições. O vendedor ao qual está se associando deve acessar o painel do Mshops, entrar na seção de clientes e finalizar o fluxo de validações. Mais informações em nosso devsite.

{
    "message": "Signature not found by user_id and checkpoint_id",
    "error": "unauthorized",
    "status": 401,
    "cause": []
}

O client_id não tem permissão para acessar as informações do vendedor. A funcionalidade é exclusiva para parceiros selecionados.

{
    "message": "Client.id not allowed to continue operation",
    "error": "unauthorized",
    "status": 401,
    "cause": []
}

Verificar o access_token:

{
    "message": "invalid_token",
    "error": "unauthorized",
    "status": 401,
    "cause": []
}

Não tem permissão para realizar a consulta. Verifique se tem permissão através do integrador para consultar esta API.:

{
    "message": "ACCESS_TOKEN_NOT_GRANTED",
    "error": "forbidden",
    "status": 403,
    "cause": []
}

O vendedor não tem mais vendas associadas ao scroll_id dado. Ou seja, a paginação já foi concluída:

{
    "message": "There is no more info associated with this scroll_id",
    "error": "not_found",
    "status": 404,
    "cause": []
}

Foram feitas muitas solicitações em um curto período de tempo:

{
    "message": "Over quota",
    "error": "too_many_requests",
    "status": 429,
    "cause": []
}

Devido a um erro inesperado em qualquer etapa do fluxo. Entre em contato conosco para determinar qual foi a causa.:

{
    "error": "Internal_server_error",
    "status": 500,
    "cause": []
}