Gerenciamento de Pixels

Com o recurso /shops/custom-scripts/ext/integration, você pode implementar e gerenciar scripts personalizados nas lojas dos vendedores do Mercado Shops, assim como desativá-los quando necessário.

Considerações

• Registre seu aplicativo em https://developers.mercadolibre.com para obter um application_id. (O aplicativo deve ser registrado no Mshops).
• Use Oauth para autorizar as solicitações, garantindo interações seguras e autenticadas com nossa plataforma.
• Cada application_id está associado a um único pixel_id. Para adquirir outro, você deve registrar outro aplicativo. Por sua vez, um pixel_id pode ter múltiplos vendedores associados.
• A associação de scripts requer que o vendedor tenha um domínio delegado no Mercado Shops. Se este requisito não for atendido, a API gerará um erro 401 (mais info.)

Scripts

• O formato dos scripts deve ser um template Handlebars, de forma que seja possível obter um código JavaScript ao substituir a variável de usuário. O código JavaScript obtido do script deve poder ser executado dentro de uma condição.
• Mantenha o script abaixo de 2kB. Se você precisar de lógica adicional, faça uma chamada para um arquivo JavaScript externo armazenado em um CDN fornecido pelo Integrador.
• Certifique-se de que os nomes do arquivo JSON sejam simples, evitando espaços e caracteres especiais para garantir a compatibilidade.
• Inclua a variável definida no arquivo .JSON no seu script. Esta variável pode ser nomeada como VARIABLE.

Exemplo de script correto:

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); 
  } 

Como será exibido na loja:

  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);

Exemplo de script incorreto:

  <script 
  src="https://test-pixel.com/api/script/mercadoshops/onLoad.js?store={{VARIABLE}} async defer></script>

Identificar o Domínio da Loja

Antes de começar o processo de configuração dos pixels, é importante ter acesso aos dados do domínio das lojas no Mercado Shops. Isso permite, em primeiro lugar, identificar se o domínio está delegado ou não, e também obter as informações necessárias para adicionar scripts personalizados. Para facilitar isso, disponibilizamos as informações por meio do seguinte recurso.

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/shops/public-domains

Resposta:

{
    "domain": "www.shop.domain.com",
    "shop_id": 123242154125,
    "status": "ACTIVE",
    "delegation_type": "PARTIAL",
    "site": "MCO"
}

Parâmetros:

Campos	Descrição do campo	Possíveis valores para o campo e sua descrição
domain	Domínio delegado	String
shop_id	ID da loja	Long
status	Estado da delegação	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 delegação	TOTAL, PARTIAL
site	ID do site do vendedor	MLA, MBO, MLB, MLC, MCO, MCR, MRD, MCU, MEC, MGT, MHN, MLM, MNI, MPA, MPY, MPE, MPT, MSV, MLU, MLV

Erros:

Status_Code	Código de erro	Mensagem de erro	Descrição
401	unauthorized	O vendedor deve solicitar a validação de sua identidade	O vendedor não validou sua identidade.
401	unauthorized	Assinatura não encontrada por user_id e checkpoint_id	O vendedor não assinou os termos e condições.
401	unauthorized	Client.id não permitido para continuar a operação	O client_id não tem permissão para acessar as informações do vendedor.
401	unauthorized	invalid_token
403	forbidden	ACCESS_TOKEN_NOT_GRANTED	Você não tem permissão para realizar a consulta.
404	not_found	shop_id não encontrado em kvs	O vendedor não possui delegação de domínios.
429	too_many_requests	Over quota	Muitos pedidos foram feitos em um curto período de tempo.
500	internal_server_error		Erro interno.

Associar script ao Shop do vendedor

Com o seguinte recurso https://api.mercadolibre.com/shops/custom-scripts/ext/integration, você poderá adicionar scripts personalizados que melhorem e adaptem as lojas do Mercado Shops, oferecendo uma melhor experiência de compra para os clientes.

Parâmetros:

Campos	Descrição do campo	Valores possíveis para o campo e sua descrição
pixel_id	Identificação do script da aplicação.	String
sections	Contém os argumentos que indicam a(s) seção(ões) da loja onde o pixel será impactado. A escrita em minúsculas deve ser respeitada e pelo menos uma seção deve ser indicada. Se nenhuma for especificada ou o nome estiver incorreto, um erro 400 será retornado.	Os valores possíveis são: home, search, cart, vip e contact.
external_client_id	ID do vendedor ao qual o pixel será aplicado.	String
integration_id	Identificador da integração previamente criada para o vendedor no endpoint POST. É o valor retornado correspondente ao id.	String

Chamada:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d
    {...}
https://api.mercadolibre.com/shops/custom-scripts/ext/integration

Exemplo:

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

Resposta:

{
  "id": "XXXXX",
  "pixel": {
    "id": "XXXXX",
    "description": "XXXXX"
  },
  "created_at": "XXXXX",
  "sections": ["home", "search", "vip", "cart", "contact"]
}

Status Code:

Status Code	Response body	Notas
201 - Created	Dados da integração recém-criada (id, data de criação, seções, detalhes do pixel).	É importante guardar o id retornado por este endpoint, ele deve ser utilizado ao desabilitar a integração.
400 - Unauthorized	{ "error": "Unauthorized Shop", "message": "Shop does not have a valid domain" }	A loja a que pretende integrar não tem domínio delegado.
400 - Bad Request	{ "error": "Active integration already exists", "message": "Seller already has an active integration with this script" }	A integração que você está tentando executar já está ativa no domínio do vendedor.
400 - Bad Request	{ "error": "Script doesn't exist", "message": "Unable to find the script with the provided ID: " }	O script que você deseja integrar na loja não existe.
401 - "error": "Unauthorized", "message": "You are unauthorized for this request" }	O token de autorização não é válido.
403	forbidden	ACCESS_TOKEN_NOT_GRANTED	Você não tem permissão para realizar a consulta.
404	not_found	shop_id not found in kvs	O vendedor não tem delegação de domínio.
429	too_many_requests	Over quota	Muitos pedidos foram feitos em pouco tempo.
500	internal_server_error		Erro interno.

Desativar pixel

Com o seguinte recurso, você poderá desativar o pixel em todas as seções em que foi ativado anteriormente para o usuário (vendedor).

Chamada:

curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shops/custom-scripts/ext/integration?integration_id={INTEGRATION_ID}

Exemplo:

curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shops/custom-scripts/ext/integration?integration_id={INTEGRATION_ID}

Resposta:

{
  "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" }	A integração já havia sido desativada anteriormente.
400 - Bad Request	{ "error": "Integration doesn't exist", "message": "The integration doesn't exist" }	A integração que você deseja desativar não existe.
401 - Unauthorized	{ "error": "Unauthorized", "message": "You are unauthorized for this request" }	O token de autorização não é válido.
500 - Internal Server Error		Erro interno.