Pular para o conteúdo principal

​
Visão Geral

A geração de conteúdo por surface permite criar versões específicas por canal do conteúdo de produto, otimizadas automaticamente para os requisitos de cada plataforma. Em vez de editar manualmente títulos para o limite de caracteres do Google Shopping ou reescrever descrições para telas mobile, a IA adapta o conteúdo com base nas restrições de surface definidas.

​
Pré-requisitos

  • Um workspace com pelo menos um catálogo e produtos
  • Chave de API com escopo write:surfaces (para uso via API)
  • Pelo menos uma surface disponível (system surfaces estão sempre disponíveis)

​
Gerar via Canvas

A forma mais simples de gerar conteúdo adaptado por surface é pela UI do Canvas:
1

Abra o Canvas para um produto

Navegue até seu catálogo, encontre o produto e abra seu Canvas.
2

Selecione uma surface

Use o seletor de surface no topo do Canvas. Escolha entre system surfaces (Google Shopping, OpenAI Commerce, etc.) ou qualquer surface customizada configurada no seu workspace.
3

Gere o conteúdo

Clique em qualquer ação do Canvas (Texto, SEO, etc.). A IA aplica as restrições de surface automaticamente — títulos respeitarão o comprimento máximo, o tom corresponderá aos requisitos da surface, e as dicas de formato guiarão o resultado.
4

Revise e confirme

Revise o conteúdo gerado no preview da surface. Quando satisfeito, confirme o conteúdo. Ele é armazenado como override de surface para este produto.
5

Conteúdo disponível

O override fica imediatamente disponível para todos os canais. O próximo sync do feed Canal 1, resultado de busca Canal 2, ou chamada de ferramenta Canal 3 para este produto + surface retornará o conteúdo adaptado.

​
Gerar via API

​
Passo 1: Listar surfaces disponíveis

curl "https://app.alana.shopping/api/workspace/{workspaceId}/surfaces" \
  -H "Authorization: Bearer SUA_CHAVE_API"
Resposta: 
{
  "surfaces": [
    {
      "id": "...",
      "surface_key": "google_shopping",
      "display_name": "Google Shopping",
      "is_system": true,
      "constraints": {
        "max_title_length": 150,
        "max_description_length": 5000,
        "tone": "seo-optimized"
      }
    }
  ]
}

​
Passo 2: Gerar conteúdo com restrições de surface

curl -X POST "https://app.alana.shopping/api/ai/generate" \
  -H "Authorization: Bearer SUA_CHAVE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "brandId": "BRAND_ID",
    "productId": "PRODUCT_ID",
    "type": "text",
    "surfaceKey": "google_shopping"
  }'

​
Passo 3: Ler o produto resolvido

curl "https://app.alana.shopping/api/workspace/{workspaceId}/products/{productId}/surfaces/google_shopping" \
  -H "Authorization: Bearer SUA_CHAVE_API"
Resposta: 
{
  "product": {
    "productId": "...",
    "surface_key": "google_shopping",
    "resolved": {
      "title": "Blazer Linho Orgânico Navy | Sustentável Premium",
      "description": "Blazer premium de linho orgânico na cor navy..."
    },
    "overrides": {
      "title": "Blazer Linho Orgânico Navy | Sustentável Premium"
    },
    "cached": true
  }
}

​
Passo 4: Definir overrides manualmente (opcional)

Pule a geração de IA e defina overrides diretamente: 
curl -X PUT "https://app.alana.shopping/api/workspace/{workspaceId}/products/{productId}/surfaces/google_shopping" \
  -H "Authorization: Bearer SUA_CHAVE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "overrides": {
      "title": "Meu título customizado para Google Shopping",
      "description": "Minha descrição customizada para Google"
    }
  }'

​
Servir pelos Canais

​
Canal 1 — Feed API

Overrides de surface são aplicados automaticamente quando a plataforma mapeia para uma surface: 
GET https://app.alana.shopping/api/mcp/feed/google_shopping?workspace_id={workspaceId}&catalog_id={catalogId}

​
Canal 2 — Search API

GET https://app.alana.shopping/api/mcp/search?workspace_id={workspaceId}&surface=google_shopping&q=blazer

​
Canal 3 — MCP Tools

{
  "tool": "get_surface_product",
  "params": {
    "product_id": "PRODUCT_ID",
    "workspace_id": "WORKSPACE_ID",
    "surface_key": "agent_response"
  }
}

​
Criar Surfaces Customizadas

curl -X POST "https://app.alana.shopping/api/workspace/{workspaceId}/surfaces" \
  -H "Authorization: Bearer SUA_CHAVE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "surface_key": "tiktok_shop",
    "display_name": "TikTok Shop",
    "constraints": {
      "max_title_length": 34,
      "max_description_length": 200,
      "tone": "casual",
      "format_hints": "Frases curtas e impactantes. Use emojis com moderação. Foco em apelo de tendência."
    }
  }'
O surface_key deve seguir o padrão ^[a-z][a-z0-9_]{1,48}[a-z0-9]$. Não pode ser alterado após a criação.

​
Excluir um Surface Override

Para reverter um produto para o conteúdo universal em uma surface: 
curl -X DELETE "https://app.alana.shopping/api/workspace/{workspaceId}/products/{productId}/surfaces/google_shopping" \
  -H "Authorization: Bearer SUA_CHAVE_API"

​
Boas Práticas

  • Comece com system surfaces para plataformas padrão (Google Shopping, OpenAI Commerce). Elas são pré-configuradas com restrições otimizadas.
  • Use o Canvas para geração em vez de definir overrides manualmente — a IA produz resultados melhores quando entende as restrições de surface durante a geração.
  • Crie surfaces customizadas com critério — cada nova surface adiciona overhead de geração de conteúdo e armazenamento por produto.
  • Revise antes de publicar — o conteúdo gerado por surface deve ser revisado, especialmente quanto a tom e precisão, antes de ser usado em canais de produção.
  • Aquecimento de cache — após criar uma surface ou atualizar restrições, o cache warmer executa automaticamente para os 100 principais produtos.
Last modified on March 19, 2026