Pular para o conteúdo principal

Referência de personalização

Referência técnica para os endpoints da API de personalização da Fashion.AI. Para obter uma visão geral dos tipos de recomendações e de como nossa IA funciona, consulte Introdução às recomendações.

Configuração básica​

Endpoint básico​

https://catalog.api.fashionai.dev/api/v1/products/protected/recommendation

Cabeçalhos necessários​

{
  “Content-Type”: “application/json”,
  “X-FashionAI-APP-Token”: “<your_app_token>”
}

Gere seu token em: https://app.generativecrm.com/settings?tab=app-tokens

Como nossa IA funciona​

Processo de mapeamento de intenções​

  1. Navegação pelo produto: rastreia os produtos pelos quais os usuários navegaram durante a sessão
  2. Elementos da categoria: analisa elementos visuais como silhuetas, padrões e detalhes de estilo
  3. Informações sobre padrões: identifica texturas, tecidos e elementos estruturais
  4. Intenção de estilo: compreende a ocasião, as preferências de estilo e as necessidades de versatilidade
  5. Comportamento do usuário: cruza referências de pesquisas, produtos e compras anteriores para usuários conectados
  6. Previsão de intenção: relaciona produtos de diferentes categorias com base no mapeamento de estilo

Endpoints da API​

Evento productView​

Quando um usuário clica em um produto, um evento de visualização do produto deve ser acionado para o Fashion.AI, mostrando ao usuário um conjunto de produtos semelhantes. Se o usuário estiver conectado, o Fashion mostra um conjunto específico de produtos com base em seu histórico. Este evento é um forte sinal da intenção do usuário e ajuda a IA a mapear a intenção do usuário, servindo como base para a organização da loja, recomendações de produtos e enriquecimento do perfil de CRM.

Corpo da solicitação​

{
  “userId”: “90”,            // opcional - identificador do usuário, se autenticado
  “sessionId”: “sess456”,    // obrigatório
  “eventType”: “productView”, // obrigatório
  “data”: {
    “id”: “id789”      // obrigatório - ID do produto
  }
}

Resposta esperada​

{
  “products”: [“product-id-1”, “product-id-2”, “product-id-3”]
}

⚠️ Observação 1: esta resposta inclui todos os produtos semelhantes classificados por sessão e relevância do usuário, que podem ser usados para organizar a loja virtual.

⚠️ Observação 2: esta resposta ficará vazia enquanto a IA não tiver dados suficientes sobre o usuário e/ou a sessão. Nesses casos, organize a loja virtual de acordo com a solução nativa da sua plataforma.

Evento categoryView​

Quando um usuário visita uma página de categoria (por exemplo, “Calças”), um evento de visualização de categoria deve ser acionado para o Fashion.AI. Se o usuário estiver conectado, o Fashion exibe uma visualização de categoria específica com base em seu histórico. Este evento é um forte sinal da intenção do usuário e ajuda a IA a mapear a intenção do usuário, servindo como base para a organização da loja virtual, recomendações de produtos e enriquecimento do perfil de CRM.

Corpo da solicitação​

{
  “userId”: “90”,            // opcional - identificador do usuário, se autenticado
  “sessionId”: “sess456”,    // obrigatório
  “eventType”: “categoryView”, // obrigatório
  “data”: {
    “id”: “category789”      // obrigatório - ID da categoria
  }
}

Resposta esperada​

{
  “products”: [“product-id-1”, “product-id-2”, “product-id-3”]
}

⚠️ Observação 1: esta resposta inclui todos os produtos da categoria classificados por sessão e relevância do usuário, que podem ser usados para a organização da loja virtual.

⚠️ Observação 2: esta resposta ficará vazia enquanto a IA não tiver dados suficientes sobre o usuário e/ou a sessão. Nesses casos, organize a loja de acordo com a solução nativa da sua plataforma.

Evento shopTheLook​

Habilite o botão “Compre o look” para exibir, por meio de modal ou gaveta, produtos adicionais que compõem o look completo de uma peça principal.

Corpo da solicitação​

{
  “userId”: “90”,            // opcional - identificador do usuário, se autenticado
  “sessionId”: “sess456”,    // obrigatório
  “eventType”: “shopTheLook”, // obrigatório
  “data”: {
    “id”: “product789”       // obrigatório - ID do produto
  }
}

Resposta esperada​

{
  “products”: [“product-id-1”, “product-id-2”, “product-id-3”]
}

⚠️ Observação: embora a API filtre produtos fora de estoque, a validação do estoque deve ser feita localmente antes da renderização no front-end.

Evento customShelf​

Retorna uma lista de produtos personalizada com base no comportamento de navegação do usuário durante a sessão. Use este evento para popular prateleiras customizadas sem vincular a recomendação a um produto ou categoria específica.

Corpo da solicitação​

{
  "userId": "90",            // opcional - identificador do usuário, se autenticado
  "sessionId": "sess456",    // obrigatório
  "eventType": "customShelf", // obrigatório
  "data": {
    "id": ""                 // obrigatório - enviar como string vazia
  }
}

Resposta esperada​

{
  "products": ["product-id-1", "product-id-2", "product-id-3"]
}

⚠️ Observação: a resposta será vazia enquanto a IA não tiver dados suficientes sobre o usuário e/ou sessão. Nestes casos, organize a vitrine conforme a solução nativa da sua plataforma.

Configurações de Recomendação​

O painel de configurações permite definir filtros para cada tipo de recomendação individualmente. Acesse as configurações e selecione a aba correspondente ao tipo desejado: Produto, Categoria ou Compre o Look. Cada tipo deve ser salvo separadamente.

Na página de Personalização, em Guia para Implementação da API clique no botão Filtros de recomendação para abrir o painel de configurações:

Página de Personalização com botão de filtros de recomendação

O modal de configurações será exibido com os filtros disponíveis para cada tipo de recomendação:

Modal de configurações de recomendação

Filtros disponíveis​

Grade quebrada​

Quando ativado, a IA prioriza produtos que complementem a grade de tamanhos do estoque atual, recomendando itens que ajudem a equilibrar a disponibilidade de tamanhos.

Desconto​

Filtra os produtos recomendados com base no status de desconto:

OpçãoDescrição
Todos os produtosRecomenda produtos independentemente de estarem em promoção ou não
Apenas com descontoRecomenda somente produtos que possuem desconto ativo
Apenas sem descontoRecomenda somente produtos com preço cheio

Faixa de preço​

Define o intervalo de preço dos produtos recomendados. Há três modos disponíveis:

ModoDescrição
Faixa customizadaPermite definir manualmente os valores mínimo e máximo através do controle deslizante
Acima de 10 milFiltra apenas produtos com preço acima de R$ 10.000,00
Todos os produtosNão aplica filtro de preço — recomenda produtos de qualquer valor

Estoque baixo​

Quando ativado, a IA não incluirá produtos com estoque baixo nas recomendações. Aparecerá o campo Limite, permitindo selecionar o número que a sua empresa considere estoque baixo (por exemplo, 10 significa que produtos com 10 ou menos unidades em estoque não serão recomendados).

Como salvar​

  1. Selecione a aba do tipo de recomendação que deseja configurar (Produto, Categoria ou Compre o Look)
  2. Ajuste os filtros conforme desejado
  3. Clique em Salvar para aplicar as configurações daquele tipo
  4. Para redefinir os filtros, clique em Limpar

⚠️ Observação: cada tipo de recomendação possui sua própria configuração. Alterações feitas em uma aba não afetam as demais. Certifique-se de salvar cada tipo individualmente.

Segurança e CORS​

Para proteger o token de autenticação (X-FashionAI-APP-Token), bloqueamos solicitações diretas do navegador. Se uma chamada de API for feita diretamente do front-end, o navegador bloqueará essa solicitação com um erro CORS.

Essa medida evita que o token seja exposto no código-fonte do site, o que poderia comprometer a segurança da API e permitir o uso não autorizado.

Se sua equipe ainda optar por fazer chamadas diretamente do front-end, basta solicitar a autorização de domínio ao suporte técnico da FashionAI. 📫 support@generativecrm.com