> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alana.shopping/llms.txt
> Use this file to discover all available pages before exploring further.

# Geração de Conteúdo por Surface

> Gere e gerencie conteúdo de produto adaptado por surface usando a API e o Canvas.

## 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:

<Steps>
  <Step title="Abra o Canvas para um produto">
    Navegue até seu catálogo, encontre o produto e abra seu Canvas.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Gerar via API

### Passo 1: Listar surfaces disponíveis

```bash theme={null}
curl "https://app.alana.shopping/api/workspace/{workspaceId}/surfaces" \
  -H "Authorization: Bearer SUA_CHAVE_API"
```

Resposta:

```json theme={null}
{
  "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

```bash theme={null}
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

```bash theme={null}
curl "https://app.alana.shopping/api/workspace/{workspaceId}/products/{productId}/surfaces/google_shopping" \
  -H "Authorization: Bearer SUA_CHAVE_API"
```

Resposta:

```json theme={null}
{
  "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:

```bash theme={null}
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:

```bash theme={null}
GET https://app.alana.shopping/api/mcp/feed/google_shopping?workspace_id={workspaceId}&catalog_id={catalogId}
```

### Canal 2 — Search API

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

### Canal 3 — MCP Tools

```json theme={null}
{
  "tool": "get_surface_product",
  "params": {
    "product_id": "PRODUCT_ID",
    "workspace_id": "WORKSPACE_ID",
    "surface_key": "agent_response"
  }
}
```

## Criar Surfaces Customizadas

```bash theme={null}
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:

```bash theme={null}
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.