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
Gestión de pixels
Consideraciones
- La aplicación debe estar registrada en https://developers.mercadolibre.com , obteniendo el application_id. (Se debe dar de alta la aplicación en Mshop).
- Para autorizar las peticiones, se utiliza Oauth (más info).
- Tener presente que un aplication_id, solo puede contar con un pixel_id. Para adquirir otro, debes dar de alta otra aplicación. a su Vez, un Pixel_id puede tener múltiples seller asociados
- Para realizar la asociación de un script a un seller, éste último debe haber delegado un dominio en MercadoShops. Si este paso no se realizó, la API devolverá un status code 401 con el siguiente mensaje: Your shop is not authorized for this request, you must have a delegated domain . Para identificar si el seller cuenta con dominio delegado o no (más info.)
- El formato de los scripts debe ser un template de Handlebars tal que se pueda obtener un código de JavaScript al reemplazar la variable de usuario. El código de JavaScript obtenido del script debe poder ser ejecutado dentro de una condición. Adicionalmente, es preferible que el script se mantenga lo más acotado posible, de tamaño total menor a 2kB, y si fuera necesaria lógica adicional, el script debe hacer un llamado para traer y ejecutar otro archivo de JavaScript almacenado en un CDN proporcionado por el Integrador.
- El nombre del archivo .Json no puede llevar espacios o caracteres especiales, Custom-script no los permite en los nombres de los Pixels.
- El script debe contener la variable que se define en el archivo .Json. Es factible llamar VARIABLE a la variable.
Ejemplo de scripts correcto:
script.hbs
if (/*condition*/) {
var
src="https://test-pixel.com/api/script/mercadoshops/onLoad.js?=shop123"; var script = document.createElement("script");
script.setAttribute("src", src);
document.getElementsByTagName("head")[0].appendChild(script);
}
Este scripts se mostrará en la tienda de la siguiente manera:
var src="https://test-pixel.com/api/script/mercadoshops/onLoad.js?={{VARIABLE}}"; var script = document.createElement("script");
script.setAttribute("src", src);
document.getElementsByTagName("head")[0].appendChild(script);
Ejemplo de scripts incorrecto:
Glosario de campos y parámetros
Campos | Descripción del campo | Valores posibles para el campo y su descripción |
---|---|---|
pixel_id | Identificación del script de la aplicación. | String |
sections | Contiene los argumentos que indican la/s secciones de la tienda donde se impactará el pixel. Se debe respetar minúsculas y como mínimo debe indicarse una sección. Si no se indica ninguna o el nombre es incorrecto, se devolverá un error 400. | Los valores posibles son: home, search, cart, vip y contact. |
external_client_id | Id del vendedor, al que se le aplicará el pixel. | String |
integration_id | Identificador de la integración previamente creada al vendedor en el endpoint POST. Es el valor de la respuesta correspondiente al id. | String |
Identificar el Dominio de la tienda
Llamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/shops/public-domains
Respuesta:
{
"domain": "www.shop.domain.com",
"shop_id": 123242154125,
"status": "ACTIVE",
"delegation_type": "PARTIAL",
"site": "MCO"
}
Parámetros de la respuesta
Campos | Descripción del campo | Valores posibles para el campo y su descripción |
---|---|---|
domain | Dominio delegado | String |
shop_id | Id de la shop | Long |
status | Estado de la delegación | REGISTERED, CHECK_FOR_TOTAL_DELEGATION, CHECK_FOR_PARTIAL_DELEGATION, DELEGATION_OK, DELEGATION_ERROR, CERTIFICATE_OK, CERTIFICATE_ERROR, NAVIGATION_OK, NAVIGATION_ERROR, ACTIVE, ERROR, DOMAIN_EXPIRED, CERTIFICATE_EXPIRED, INACTIVE, DELEGATION_CEASED, DELEGATION_ANALYZE, DELEGATION_RESTART, DELEGATION_PREVIOUS, DELEGATION_REREGISTER, CERTIFICATE_ANALYZE, NAVIGATION_ANALYZE, ANALYZE |
delegation_type | Tipo de la delegación | TOTAL, PARTIAL |
site | Id del site del seller | MLA, MBO, MLB, MLC, MCO, MCR, MRD, MCU, MEC, MGT, MHN, MLM, MNI, MPA, MPY, MPE, MPT, MSV, MLU, MLV |
Errores
Status_Code | Código de error | Mensaje de error | Descripción |
---|---|---|---|
401 | unauthorized | Seller has pending to ask their identity validation | El vendedor no validó su identidad |
401 | unauthorized | Signature not found by user_id and checkpoint_id | El vendedor no firmó los términos y condiciones. |
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. |
401 | unauthorized | invalid_token | |
403 | forbidden | ACCESS_TOKEN_NOT_GRANTED | No tiene permisos para realizar la consulta. |
404 | not_found | shop_id not found in kvs | El vendedor no cuenta con delegación de dominios. |
429 | too_many_requests | Over quota | Se hicieron demasiados requests en un corto periodo de tiempo. |
500 | internal_server_error | Se debe a un error no esperado en cualquier paso del flujo. |
Asociar script al Shop del vendedor
Llamada:
curl -X POST-H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d
{...}
https://api.mercadolibre.com/shops/custom-scripts/ext/integration
Ejemplo:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d
'{
"pixel_id": "XXXXX",
"sections": ["home", "search", "vip", "cart", "contact"],
"external_client_id": "XXXXX",
}
'
https://api.mercadolibre.com/shops/custom-scripts/ext/integration
Respuesta:
{
"id": "XXXXX",
"pixel": {
"id": "XXXXX",
"description": "XXXXX"
},
"created_at": "XXXXX",
"sections": ["home", "search", "vip", "cart", "contact"]
}
Status Code | Response body | Notas |
---|---|---|
201 - Created | Datos de la integración recién creada (id, fecha de creación, secciones, detalles del pixel). | Es importante guardar el id que devuelve este endpoint, ya que debe ser usado al momento de deshabilitar la integración. |
400 - Unauthorized | { "error": "Unauthorized Shop", "message": "Shop does not have a valid domain" } | El shop al que se quiere realizar la integración no tiene dominio delegado. |
400 - Bad Request | { "error": "Active integration already exists", "message": "Seller already has an active integration with this script" } | La integración que se intenta realizar ya se encuentra activa en el dominio del Seller. |
400 - Bad Request | { "error": "Script doesn't exist", "message": "Unable to find the script with the provided ID: " } | No existe el script que se quiere integrar al shop. |
401 - Unauthorized | { "error": "Unauthorized", "message": "You are unauthorized for this request" } | El token de autorización no es válido. |
500 - Internal Server Error | Error interno. |
Desactivar pixel
Con el el siguiente recurso podrás desactivar el pixel en todas las secciones en que se activó previamente al usuario (vendedor).
Llamada:
curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shops/custom-scripts/ext/integration?integration_id={INTEGRATION_ID}
Ejemplo:
curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shops/custom-scripts/ext/integration?integration_id={INTEGRATION_ID}
Respuesta:
{
"updated_at": "XX/XX/XX",
"status": "Disabled",
"external_client_id": "XXXXX"
}
Status Code
Status Code | Response body | Notas |
---|---|---|
200 - OK | ||
400 - Bad Request | { "error": "Integration already disabled", "message": "It is not possible to process your request. The integration is already disabled" } | La integración ya se había deshabilitado anteriormente. |
400 - Bad Request | { "error": "Integration doesn't exist", "message": "The integration doesn't exist" } | No existe la integración que se busca deshabilitar. |
401 - Unauthorized | { "error": "Unauthorized", "message": "You are unauthorized for this request" } | El token de autorización no es válido. |
500 - Internal Server Error | Error interno. |