Pular para o conteúdo principal

​
O que são Surfaces?

Uma Surface é um contexto de exibição nomeado que define como o conteúdo de produtos deve ser adaptado para um canal de distribuição ou plataforma específica. Cada surface tem restrições — comprimento máximo de título, tom de voz, dicas de formato — que orientam a IA ao gerar conteúdo. Sem surfaces, o Canvas gera conteúdo “universal”: uma única versão do título, descrição e atributos de cada produto que serve como padrão em todos os canais. Com surfaces, você pode gerar versões específicas por canal que são otimizadas para os requisitos de cada plataforma.

​
System Surfaces

A Alana fornece cinco surfaces pré-configuradas que cobrem os canais de distribuição mais comuns. System surfaces não podem ser excluídas, mas você pode gerar overrides para qualquer produto em qualquer uma delas.
Surface KeyNomeTítulo Máx.Descrição Máx.Tom
google_shoppingGoogle Shopping150 chars5000 charsSEO-otimizado
openai_commerceOpenAI Commerce200 chars2000 charsConversacional
mobile_pdpPágina do Produto Mobile65 chars300 charsConciso
desktop_pdpPágina do Produto Desktop200 chars2000 charsDetalhado
agent_responseResposta de Agente IA100 chars500 charsLinguagem natural

​
Surfaces Customizadas

Workspaces podem criar surfaces customizadas para qualquer contexto de exibição necessário. Uma surface customizada tem um surface_key único (letras minúsculas, dígitos e underscores), um nome de exibição e restrições opcionais. Exemplos de surfaces customizadas:
  • tiktok_shop — descrições curtas otimizadas para intenção de compra no TikTok
  • trade_show_kiosk — formato de tela grande com headlines marcantes
  • whatsapp_catalog — formato de API de catálogo do WhatsApp Business
  • b2b_wholesale — especificações técnicas em tom formal
Surfaces customizadas são criadas e gerenciadas em Configurações > Surfaces, ou via a API de Surfaces.

​
Como a Resolução de Surfaces Funciona

Quando um canal solicita conteúdo de produto com um contexto de surface, a Alana resolve o conteúdo em um cache de três camadas: 
1. Cache hit?    → Retorna produto resolvido do cache (< 5ms)
2. Null marker?  → Sem override → Retorna conteúdo universal
3. DB lookup     → Busca override → Deep merge → Cache e retorna
A lógica de resolução: 
universal = catalog_products[product_id]             // sempre presente
overrides = product_surfaces[product_id, surface_key] // pode não existir
resolved  = deepMerge(universal, overrides)           // surface vence onde presente
Se não existir override de surface para um produto, o conteúdo universal é retornado sem alterações. As surfaces são sempre retrocompatíveis — consumidores de API que não passam surface_key recebem o mesmo conteúdo universal de antes.

​
Surface Overrides

Um surface override é um conjunto parcial de campos de produto armazenado por-produto, por-surface na tabela product_surfaces. Overrides são gerados por:
  • Canvas: Selecione uma surface antes de gerar conteúdo; a IA aplica as restrições automaticamente
  • API: PUT com campos parciais de produto em /api/workspace/{id}/products/{pid}/surfaces/{key}
  • Bulk: Gere overrides para múltiplos produtos via Batch API
Apenas os campos presentes no override substituem os valores universais. Campos não presentes no override continuam vindo do registro universal do produto.

​
Surfaces nos Canais

Cada canal resolve surfaces de forma diferente:

​
Canal 1 — Feed API

A plataforma determina a surface implicitamente. Não há parâmetro surface na query — o endpoint do feed seleciona a surface com base na plataforma: 
GET /api/mcp/feed/google_shopping?workspace_id={id}
# → surface_key = "google_shopping" aplicado automaticamente
Plataformas sem surface_key correspondente (ex.: vtex, shopify, nuvemshop) recebem conteúdo universal.

​
Canal 2 — Search API

Passe o parâmetro surface na query para receber conteúdo adaptado: 
GET /api/mcp/search?workspace_id={id}&surface=mobile_pdp&q=shoes
# → Retorna títulos ≤ 65 chars, descrições ≤ 300 chars
Omitir surface retorna conteúdo universal.

​
Canal 3 — MCP Tools

Agentes IA podem solicitar conteúdo com surface aplicada usando o parâmetro surface nas chamadas de ferramentas, ou usar as ferramentas dedicadas de surface:
  • list_surfaces — enumerar surfaces disponíveis para um workspace
  • get_surface_product — buscar produto com uma surface específica aplicada
Veja MCP Tools para a referência completa de ferramentas.
Last modified on March 19, 2026