API de beleza para e-commerce headless: onde ela encaixa em uma arquitetura composable

As equipes de e-commerce de beleza que migraram para um stack composable costumam descobrir a mesma coisa: os plugins de loja que antes resolviam tudo já não se aplicam. Quando o front é um framework próprio e o catálogo vive em um serviço à parte, cada capacidade nova entra como serviço. Uma API de beleza para e-commerce headless segue essa mesma lógica: em vez de instalar uma extensão na plataforma, você chama um endpoint, recebe JSON e decide como aquilo aparece e onde.

Este artigo organiza as decisões de arquitetura: qual camada faz o quê, o que roda no servidor e o que roda no navegador, onde guardar o perfil de beleza e como tratar erros sem quebrar a página de produto.

As três camadas de uma experiência de beleza

Antes de desenhar a integração, convém separar três funções que muitas vezes se confundem em uma única "solução de beleza".

Camada de perfil: entender o cliente

O cliente envia uma selfie e recebe um perfil de beleza estruturado: tom e subtom de pele, tipo e condição da pele, atributos de cabelo e um nível de confiança por campo. É uma resposta JSON, não uma interface. É exatamente disso que um front headless precisa: o dado chega limpo e a equipe decide se ele aparece como card, como etapa de um quiz ou como atributo invisível que alimenta outra coisa. A análise de pele e cabelo por selfie ocupa esta camada.

Um esclarecimento importante para o briefing de produto: o perfil descreve atributos visíveis de uma foto. Não é uma avaliação clínica, não trata nem substitui um profissional de saúde. Os textos do front devem refletir isso.

Camada de visualização: ver o produto aplicado

Aqui vive a prova virtual de maquiagem. Ela tem duas formas, e a escolha é arquitetural, não estética. A API por foto recebe uma imagem e o produto (batom ou base) e devolve a imagem renderizada, com as paletas calibradas para os produtos reais da marca dentro de um projeto. O SDK de navegador, em acesso antecipado desde setembro de 2026, roda no domínio da marca e cobre treze produtos — batom, base, blush, pó facial, corretivo de olheiras, sombra, máscara de cílios, sobrancelhas, delineador, bronzer, contorno, iluminador e lápis de boca — mais um Full Look combinado, em modo ao vivo pela câmera ou em modo foto, com qualquer cor #RRGGBB.

A diferença prática: a API por foto é uma chamada servidor a servidor e serve em qualquer canal, incluindo WhatsApp ou um CRM. O SDK é código no cliente, e o render acontece localmente no navegador, sem upload da imagem. O Full Look e os onze produtos adicionais existem só no SDK.

Camada de recomendação: transformar o perfil em SKU

Um perfil sem catálogo é um dado bonito sem ação. O MaIA Beauty Advisor é a camada que lê o perfil e recomenda os produtos da própria marca no WhatsApp, nas páginas de produto e no chat. Não é self-serve: é entregue como projeto junto com a equipe da B4A, porque depende de como o seu catálogo está modelado.

API de beleza para e-commerce headless: o diagrama mínimo

Um padrão que funciona bem em stacks composable:

1. BFF (backend for frontend) como intermediário. O navegador nunca fala direto com a API de beleza. Seu BFF guarda a chave de API, agrega contexto (cliente logado, moeda, região) e normaliza a resposta.
2. Um endpoint próprio por caso de uso. Em vez de expor o JSON cru, publique /perfil e /try-on no seu próprio domínio. Assim você pode trocar de fornecedor, cachear ou mockar sem tocar no front.
3. O front consome o seu contrato, não o do fornecedor. Isso evita que um campo novo na resposta quebre o componente React ou o template Vue.
4. O catálogo manda. O mapeamento entre o perfil e os SKUs vive na sua camada de dados, junto com estoque e preço, não dentro do componente visual.

O SDK de navegador é a exceção deliberada à regra 1: roda no cliente por design, auto-hospedado pela marca, e por isso a equipe de front mantém controle total do empacotamento e do CSS.

Decisões que convém fechar antes do primeiro sprint

Onde o perfil vive

Três opções, e nenhuma é universal. Na sessão (rápido, se perde ao fechar o navegador). Na conta do cliente (permite reutilizar o perfil em e-mail, app e loja). No CRM, como atributos de segmentação. O habitual é sessão mais conta, com sincronização para o CRM quando o cliente está logado. Defina desde o início a política de retenção da imagem e do perfil, e declare isso no aviso de privacidade.

Consentimento como componente, não como letra miúda

Em headless, o consentimento é um componente reutilizável: uma tela antes da câmera, com texto claro sobre o que é enviado e o que é guardado, e um estado persistido. Fazer isso uma única vez evita que cada canal implemente do seu jeito.

Degradação elegante

O que a página de produto mostra se a chamada falhar ou o cliente negar a câmera? A resposta não pode ser uma tela em branco. Defina o fallback: seletor de tons clássico, guia de cor, formulário curto. A experiência de beleza é um acelerador de decisão, não um requisito para comprar.

Confiança por campo na lógica do front

Cada campo do perfil vem com um nível de confiança. Use-o: quando a confiança é baixa, mostre duas opções de tom em vez de uma, ou peça uma segunda foto com luz melhor. Essa regra pertence à sua camada de negócio e deve ser configurável sem redeploy.

Como começar sem comprometer o roadmap

A vantagem do modelo self-serve é que a equipe técnica pode testar antes de existir um projeto formal: você cria uma conta, compra créditos e obtém uma chave de API na documentação. Um desenvolvedor consegue ter uma chamada real respondendo em um ambiente de staging em uma tarde, com uma selfie de teste e curl.

Um plano razoável: sprint 1, chamada a partir do BFF e contrato próprio; sprint 2, componente de front com consentimento e fallback; sprint 3, persistência do perfil e primeiro uso em recomendação ou em e-mail. Só depois se discute a camada de advisor e o catálogo completo.

Vai integrar beleza em um stack composable? Crie sua conta e sua chave de API para testar a resposta real, ou fale com a equipe se precisar da camada de recomendação conectada ao seu catálogo.