Documentación Mercado Shops

Descubre toda la información que debes conocer sobre las APIs de Mercado Shops.
circulos azuis em degrade
Última actualización 24/10/2023

Gestión de pixels

Importante:
Para poder hacer uso del recurso, deberás completar el siguiente formulario, con el fin de acceder al proceso de certificación y cumplir los requisitos.

Con el recurso /shops/custom-scripts/ext/integration puedes asociar tu scripts al Shop del vendedor, como también desactivarlo.

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

Previo a comenzar el flujo de configuración de pixels es necesario tener acceso a los datos del dominio de los vendedores de Mercado Shops para poder identificar en primer lugar si el mismo cuenta o no con dominio delegado, y tambien para contar con la información del dominio de la tienda para añadir customs scripts a los integradores. Para esto permitimos disponibilizar la información mediante el siguiente recurso.

Importante:
Ten en cuenta que en la respuesta del request de /public-domains tendrás que validar que el status sea ACTIVE para permitir continuar con el flujo de configuración del pixel. En caso de recibir cualquier otro valor, deberíamos de dar aviso, que la tienda no cuenta con dominio delegado.

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"]
}
Nota:
Donde el status code sea suficientemente descriptivo, el cuerpo de la response estará vacío. En casos dónde el status code no brinda suficiente información, se incluirán en el response body los campos “error” y “message” para brindar mayor contexto sobre el error.

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.