Documentación Mercado Shops
Descubre toda la información que debes conocer sobre las APIs de Mercado Shops.
Documentación
Última actualización 24/10/2023
Acceso a datos del cliente
Consultar por intervalos de fechas
Llamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/shops/cda/customers?order_created_from=$DATE_FROM&order_created_to=$DATE_TOEjemplo:
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:00Respuesta:
'{
"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
Ya habiendo realizado la primera consulta por intervalos de fechas obteniendo el scroll_id correspondiente, se puede consultar con el valor recibido. Se debe continuar con los siguientes recursos:
Llamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/shops/cda/customers?scroll_id=$SCROLL_IDEjemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/shops/cda/customers?scroll_id=YXBpY29yZS1vcmlnaW5hbC1vcmRlcnM=:ZHMtYXBpY29yZS1vcmlnaW5hbC1vcmRlcnMtMDM=:FGluY2x1ZGVfY29udGV4dF91dWlkDXF1ZXJ5QW5kRmV0Y2gBFEs1djliWDRCdW1sSjF0ZENGS3l0AAAAAHPJOh0WRUlRNGJVc3FTUWk5ZUtLN0NEM2NDQQ==Respuesta con el listado de compradores y su información:
'{
"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=="
}
}'
Consulta por buyer_id
Llamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/shops/cda/customers?buyer_id=$BUYER_IDLlamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/shops/cda/customers?buyer_id=1080426219Respuesta con la órdenes que tiene registradas el comprador y su información.
{
"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=="
}
}
Consulta por order_id
Llamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/shops/cda/customers?order_id=$ORDER_IDEjemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/shops/cda/customers?order_id=2000005003466456Respuesta con la órden buscada y su información
{
"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=="
}
}
Glosario
Parámetros de la petición
| Campos | Descripción del campo | Valores posibles para el campo y su descripción |
|---|---|---|
| order_created_from | Fecha de inicio y fin 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 inicio y 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 |
| scroll_id | Usado para continuar la paginación de la búsqueda. | YXBpY29yZS1vcmlnaW5hb C1vcmRlcnM=:ZHMtYXBpY 29yZS1vcmlnaW5hbC1vcm RlcnMtMDM=:FGluY2x1ZG VfY29udGV4dF91dWlkDXF 1ZXJ5QW5kRmV0Y2gBFEs1 djliWDRCdW1sSjF0ZENGS 3l0AAAAAHPJOh0WRUlRNG JVc3FTUWk5ZUtLN0NEM2N DQQ== |
| buyer_id | Se usa para buscar información filtrando por el id del comprador. | 1080426219 |
| order_id | Se usa para filtrar por una orden específica. | 2000005003466456 |
Parámetros de la respuesta
| Campos | Descripción del campo | Valores posibles para el campo y su descripción |
|---|---|---|
| results | Listado de órdenes | [ ] , [order], [order, order, …] |
| paging | Información de paginación de la búsqueda | Paging [ total, limit, scroll_id] |
Order
| Campos | Descripción del campo | Valores posibles para el campo y su descripción |
|---|---|---|
| id | id de la orden | order_id |
| 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 |
| paid_amount | Monto pagado por el comprador en la orden | 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 | buyer |
| order_items | Lista de ítems comprados | [ ], [orderItem], [order_Item, orderItem, …] |
| coupon | Información del cupón usado en la orden (si aplica) | coupon |
Buyer
| Campos | Descripción del campo | Valores posibles para el campo y su descripción |
|---|---|---|
| id | Id del comprador | Id del comprador |
| person | Información del comprador, puede ser null. | person |
| contact | Información de contacto del comprador | contact |
| 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. |
Person
| Campos | Descripción del campo | Valores posibles para el campo y su descripción |
|---|---|---|
| birthday | Fecha de cumpleaños del comprador. Puede no presentarse. | Ej. 1999-01-20 formato YYYY-MM-DD |
| 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
| Campos | Descripción del campo | Valores posibles para el campo y su descripción |
|---|---|---|
| Email del comprador. | ||
| phone | Télefono del comprador. |
Coupon
| Campos | Descripción del campo | Valores posibles para el campo y su descripción |
|---|---|---|
| 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. |
OrderItem
| Campos | Descripción del campo | Valores posibles para el campo y su descripción |
|---|---|---|
| Item | Información del ítem. | Ítem. |
Ítem
| Campos | Descripción del campo | Valores posibles para el campo y su descripción |
|---|---|---|
| Title | Título de la publicación del ítem. | |
| Id | Id del ítem. |
Paging
| Campos | Descripción del campo | Valores posibles para el campo y su descripción |
|---|---|---|
| total | Total de órdenes resultantes de la búsqueda. | |
| limit | Máximo número de órdenes presentadas por página. | |
| scroll_id | Id de scroll de la búsqueda. | Para continuar la búsqueda se debe enviar este valor como parámetro en la siguiente consulta, siempre usar el último generado. |
Errores
| Status_Code | Código de error | Mensaje de error | Descripción | Posible solución |
|---|---|---|---|---|
| 400 | bad request | El intervalo de fechas debe ser enviado. | El integrador debe enviar el intervalo de fechas para poder realizar la petición | |
| 401 | unauthorized | Seller has pending to ask their identity validation | 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. |
| 401 | unauthorized | Signature not found by user_id and checkpoint_id | 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. |
| 401 | unauthorized | Client.id not allowed to continue operation | El client_id no cuenta con los permisos para acceder a la información del vendedor. | La funcionalidad es exclusiva a partners seleccionados. |
| 401 | unauthorized | invalid_token | Verificar el access_token. | |
| 403 | forbidden | ACCESS_TOKEN_NOT_GRANTED | No tiene permisos para realizar la consulta | Verificar que tenga permiso a través del integrador de consultar esta API. |
| 404 | not_found | There is no more info associated with this scroll_id | El vendedor no cuenta con más ventas asociadas al scroll_id dado. Es decir que la paginación ya finalizó. | |
| 429 | too_many_requests | Over quota | Se hicieron demasiados requests en un corto periodo de tiemp | |
| 500 | internal_server_error | Se debe a un error no esperado en cualquier paso del flujo. | Comunícate con nosotros para determinar cuál fue la causa. |