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

# Surfaces

> Adapte o conteúdo de produtos para diferentes canais de distribuição e plataformas automaticamente.

## 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 Key       | Nome                      | Título Máx. | Descrição Máx. | Tom               |
| ----------------- | ------------------------- | ----------- | -------------- | ----------------- |
| `google_shopping` | Google Shopping           | 150 chars   | 5000 chars     | SEO-otimizado     |
| `openai_commerce` | OpenAI Commerce           | 200 chars   | 2000 chars     | Conversacional    |
| `mobile_pdp`      | Página do Produto Mobile  | 65 chars    | 300 chars      | Conciso           |
| `desktop_pdp`     | Página do Produto Desktop | 200 chars   | 2000 chars     | Detalhado         |
| `agent_response`  | Resposta de Agente IA     | 100 chars   | 500 chars      | Linguagem 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](/pt/api-reference/surfaces/list-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:

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

```bash theme={null}
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](/pt/api-reference/mcp/commerce-tools) para a referência completa de ferramentas.