Geração de Conteúdo por Surface

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:

Abra o Canvas para um produto

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

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.

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.

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.

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.

Primeiros Passos

Conceitos Fundamentais

Guias

Geração de Conteúdo por Surface

Visão Geral

Pré-requisitos

Gerar via Canvas

Gerar via API

Passo 1: Listar surfaces disponíveis

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

Passo 3: Ler o produto resolvido

Passo 4: Definir overrides manualmente (opcional)

Servir pelos Canais

Canal 1 — Feed API

Canal 2 — Search API

Canal 3 — MCP Tools

Criar Surfaces Customizadas

Excluir um Surface Override

Boas Práticas

​Visão Geral

​Pré-requisitos

​Gerar via Canvas

​Gerar via API

​Passo 1: Listar surfaces disponíveis

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

​Passo 3: Ler o produto resolvido

​Passo 4: Definir overrides manualmente (opcional)

​Servir pelos Canais

​Canal 1 — Feed API

​Canal 2 — Search API

​Canal 3 — MCP Tools

​Criar Surfaces Customizadas

​Excluir um Surface Override

​Boas Práticas

Visão Geral

Pré-requisitos

Gerar via Canvas

Gerar via API

Passo 1: Listar surfaces disponíveis

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

Passo 3: Ler o produto resolvido

Passo 4: Definir overrides manualmente (opcional)

Servir pelos Canais

Canal 1 — Feed API

Canal 2 — Search API

Canal 3 — MCP Tools

Criar Surfaces Customizadas

Excluir um Surface Override

Boas Práticas