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

Acceso a datos del cliente

Los vendedores de Mercado Shops necesitan acceso a los datos de sus clientes, suscriptores y carritos abandonados para poder utilizarlos en campañas de marketing o para visualizar las ventas de manera detallada en un período determinado.

Por eso, ponemos a disposición esta información a través de varios recursos, con el objetivo de mejorar la comunicación con los compradores, optimizar la experiencia post-venta y fortalecer su fidelidad.

Importante:

Para acceder a estos recursos, es necesario completar el siguiente formulario para iniciar el proceso de certificación y cumplir con los requisitos.

Además, ten en cuenta que para utilizar la nueva versión, deberás incluir en el header: App-Version: 2.

Por último, recuerda que el vendedor debe acceder a la sección "Clientes" dentro de Mercado Shops y aceptar los Términos y Condiciones.

Consultar por intervalos de fechas

Importante:

Al realizar consultas con fechas, el sistema no considera minutos ni segundos, solo rangos de horas.

Contamos con las siguientes limitaciones en los períodos de consulta:

Suscriptores: Disponibles desde enero de 2023.
Órdenes: Disponibles desde el 25 de septiembre de 2023.
Carritos: Disponibles desde agosto de 2023.

Desde agosto 2023 se depurarán los datos que tengan más de 1 año y medio.

Con el siguiente recurso, podrás consultar los datos de clientes de todos los "type", incluyendo Órdenes, suscriptores y carritos abandonados, dentro de un intervalo de fechas específico.

Parámetros:

Campos	Descripción del campo	Valores posibles para el campo y su descripción
order_created_from	Fecha de inicio de la búsqueda. Compara contra la fecha de creación de las órdenes. Debe ser en formato ISO-8601	2021-01-18T00:00:00.000-00:00
order_created_to	Fecha de fin de la búsqueda. Compara contra la fecha de creación de las órdenes. Debe ser en formato ISO-8601	2022-01-18T00:00:00.000-00:00

Llamada:

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

Ejemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'App-Version: 2' 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

Respuesta:

'{
  "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": "75ed02ff-cd73-45f7-b0b8-cb3393eac038",
           "creation_date": "2024-05-20T12:52:11.000+00:00",
           "follower": {
               "id": "75ed02ff-cd73-45f7-b0b8-cb3393eac038",
               "contact": {
                   "email": "karisina@example.com"
               },
               "ms_seller_promotions": true,
               "buyer": false
           },
           "type": "subscriber"
       },
    {
      "id": "56ed01ff-cd73-45f7-b0b8-cb3393egc038",
      "type": "subscriber",
      "date_created": "2024-06-29T11:32:23.000+00:00",
      "follower": {
        "id": 56ed01ff-cd73-45f7-b0b8-cb3393egc038",
        "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 la respuesta

La respuesta de un GET al recurso CDA/customers?order_created_from&order_created_to proporcionará los siguientes parámetros:

id: id del type
type: tipo de documento [order, subscriber, abandoned_cart]
date_created: Fecha y hora de creación de la orden
- Fecha y hora expresada según ISO 8601 ej. 2021-06-16T17:26:41.000+00:00
amount: Monto pagado por el comprador en la orden, en carrito no se envía.
- value
currency_id: Tipo de moneda en que se realizó el pago
- Valor según el ISO 4217 de la moneda, ej. COP, MXN, ARS, CLP, BRL
buyer: Comprador de la orden
- id: Id del comprador
person:
- birthday: Fecha de cumpleaños del comprador. Puede no presentarse.
- first_name: Nombre del comprador
- last_name: Apellido del comprador
- gender: Género registrado para el comprador según su documento de identidad. Puede no presentarse.
  - “F”: femenino
  - “M”: masculino
contact:
- email: Email del comprador
- phone: Teléfono del comprador
- state: Estado en el que se encuentra la dirección
- city: Ciudad en la que se encuentra la dirección
ms_seller_promotions: Aceptación por parte del comprador de recibir información promocional por medio de sus datos de contacto.
- “true”: el comprador acepta recibir la información promocional
- “false”: el comprador no acepta recibir información promocional
subscriber: indicador si el comprador también es un follower
- true, false
items: Lista de ítems comprados. Para los type abandoned_cart y order.
- Item: Información del ítem.
- Title: Título de la publicación del ítem.
- quantity: cantidad de ítems dentro de la orden o carrito abandonado.
coupon: Información del cupón usado en la orden (si aplica)
- id: Id del cupón (Si llega null, quiere decir que no se aplicó ningún cupón de descuento en la compra.)
- amount: Descuento aplicado en la compra con el cupón.
follower: Solo para subscriber
- id: Id del suscriptor
- person: Información del comprador, puede ser null.
- contact: Información de contacto del comprador
- ms_seller_promotions: Aceptación por parte del comprador de recibir información promocional
  - “true”: el comprador acepta recibir la información promocional
- buyer: indicador si el suscriptor ha realizado una compra.
  - true, false
Paging:
- total: Total de órdenes resultantes de la búsqueda.
- limit: Máximo número de órdenes presentadas por página.
scroll_id: Usado para continuar la paginación de la búsqueda.

Consultar por scroll id

Después de realizar la primera consulta por intervalos de fechas, recibirás un scroll_id. Este valor te permitirá realizar consultas adicionales para seguir accediendo a más datos de manera eficiente.

Parámetros:

Campos	Descripción del campo	Valores posibles para el campo y su descripción
scroll_id	Usado para continuar la paginación de la búsqueda.	YXBpY29yZS1vcm1naW5hbC1vcmluRc1nMtMDM=:ZMHtYXBpY29yZS1vcm1naW5hbC1vcmRlc1nMtMDM=:FGluY2x1ZGViY29udGV4dF91dWlkDXF1ZXJ5QW5kRmVoY29gBFEs1djl1WDRCdW1sSjF0ZENGS3l0AAA...

Llamada:

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

Ejemplo:

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

Respuesta:

'
{
  "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": "75ed02ff-3gh1-45f7-b0b8-cb3393eac038",
      "type": "subscriber",
      "date_created": "2024-06-29T11:32:23.000+00:00",
      "follower": {
        "id": 75ed02ff-3gh1-45f7-b0b8-cb3393eac038,
        "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 te permite obtener la información completa del comprador, incluyendo sus órdenes y, si aplica, información sobre cualquier carrito abandonado.

Parámetros:

Campos	Descripción del campo	Valores posibles para el campo y su descripción
buyer_id	Se usa para buscar información filtrando por el id del comprador.	1080426219

Llamada:

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

Ejemplo:

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

Respuesta:

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

Con este recurso, podrás obtener información detallada sobre el comprador asociado a una orden específica utilizando el order_id. La respuesta incluirá:

Datos del comprador, como su estado de suscripción.
Detalles de la orden, incluyendo información sobre cupones aplicados.

Parámetros:

Campos	Descripción del campo	Valores posibles para el campo y su descripción
order_id	Se usa para filtrar por una orden específica.	2000005003466456

Llamada:

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

Ejemplo:

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

Respuesta:

{
  "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 y rango de fechas

Este recurso te permitirá consultar datos de compradores y suscriptores, filtrando por type (tipo de documento) y dentro de un intervalo de fechas específico.

Parámetros:

Campos	Descripción del campo	Valores posibles para el campo y su descripción
type	tipo de documento a buscar	[order, subscriber, abandoned_cart]

Llamada:

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

Ejemplo:

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

Respuesta:

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

Posibles Errores

El intervalo de fechas debe ser enviado: El integrador debe enviar el intervalo de fechas para poder realizar la petición.

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

El vendedor no validó su identidad. El vendedor al que se está asociando debe acceder al panel de Mshops, ingresar a la sección de clientes y culminar el flujo de validaciones. Más información en nuestro devsite.

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

El vendedor no firmó los términos y condiciones. El vendedor al que se está asociando debe acceder al panel de Mshops, ingresar a la sección de clientes y culminar el flujo de validaciones. Más información en nuestro devsite.

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

El client_id no cuenta con los permisos para acceder a la información del vendedor. La funcionalidad es exclusiva a partners seleccionados.

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

Verificar el access_token.

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

No tiene permisos para realizar la consulta. Verificar que tenga permiso a través del integrador de consultar esta API.

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

El vendedor no cuenta con más ventas asociadas al scroll_id dado. Es decir que la paginación ya finalizó.

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

Se realizaron demasiados requests en un corto periodo de tiempo.

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

Se debe a un error no esperado en cualquier paso del flujo. Comunícate con nosotros para determinar cuál fue la causa.

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