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

# Changelog

> Acompanhe novos recursos, melhorias e correções nas versões do Alana Shopping B2B.

## Maio de 2026

### Canvas — Action de FAQ dedicada {/* 2026-05-15 — Phase 185 */}

**Novo**

* **Nova action `faq` no Canvas** — promovida de sub-output do `semantic` para action de conteúdo de primeira classe. Cada FAQ agora carrega uma `category` (`uso`, `cuidado`, `tamanho`, `envio`, `trocas`, `material`, `estilo`, `outro`) e uma `confidence` em `[0, 1]`. A rota `/api/ai/generate` aplica post-filter em `confidence ≥ 0.7`; se sobrarem menos de 5 FAQs de alta confiança, a request retorna 400 com instrução clara de retry.
* **Tópicos proibidos** embutidos no prompt: perguntas sobre cor/tamanho/disponibilidade/preço são rejeitadas — esses dados vivem em campos estruturados do produto e responder ali risca alucinação. O prompt direciona pra caimento, cuidado/lavagem, uso/ocasião, material/composição, estilo, envio e trocas.
* **`SemanticResult.faqs` continua intacto** para back-compat — integrações existentes seguem funcionando. Novas superfícies devem adotar a action `faq` dedicada para output melhor categorizado e mais confiável.

**API**

* `POST /api/ai/generate` aceita `action: "faq"`; shape da resposta: `{ faqs: Array<{ question, answer, category, confidence }> }`.
* Tipos `FaqResult` e `FaqCategory` exportados de `@/types/optimization`.

### Roteamento por tier no Image-Edit {/* 2026-05-14 — Phase 184 */}

**Bug fix em produção**

* **`POST /api/workspace/{workspaceId}/ai-media/image-edit` agora respeita o parâmetro `tier`.** Antes a rota hardcodava `provider: "together_ai"` e chamava FLUX Kontext via LiteLLM independente do tier — `tier: "high"` ficava efetivamente sem funcionar.
* Após Phase 184 a rota resolve provider+model via `resolveProvider(action, tier)`:
  * `tier: "high"` + reshoot/backdrop → **RunwayML Gen4 Image Turbo** (submit + poll até 120s)
  * `tier: "balanced"` → FLUX Kontext Pro via Together AI (comportamento existente)
  * `tier: "economic"` → FLUX.1-schnell via Together AI
  * `relight_product` / `image_upscale` → RunPod (IC-Light v2 / Real-ESRGAN); a rota loga warning e cai pro FLUX se o path direto do RunPod não estiver configurado
* Os jobs agora refletem o **provider e model reais** (acabou o `together_ai` cosmético em todo job). Observabilidade ganha correção imediata.
* Novo helper `submitImageJobAndWait` em `src/lib/providers/runwayml.ts` — wrapper síncrono em torno de `submitImageJob` + `getImageJobStatus` para rotas que querem resposta one-shot.

## Março de 2026

### v1.8.1 — Hardening do Pipeline + Marketplace Hub {/* 2026-03-17 */}

**Pipeline de Dados**

* **Idempotência Bronze**: importações duplicadas da mesma fonte são silenciosamente ignoradas via chave hash `source_identifier` — re-executar uma importação não cria produtos duplicados
* **Pontuação de otimização unificada**: `optimization_score` agora é campo de nível raiz no objeto produto; `score_history` rastreia a progressão completa de 0 a 100 ao longo das execuções do pipeline
* **API de configurações do pipeline**: `GET/PUT /api/workspace/{workspaceId}/settings/pipeline` — configure mapeamentos de campos Silver, pesos da rubrica Gold e comportamento de auto-trigger por workspace

**Marketplace Hub**

* **Paginação**: `GET /api/hub/catalogs` agora retorna paginação baseada em cursor (params `after`, `limit`); primeira página padrão com 20 catálogos
* **Endpoint de preview**: `GET /api/hub/catalogs/{catalogId}/preview` — inspecione metadados do catálogo e uma amostra de produtos antes de clonar ou assinar
* **Assinar + sincronizar**: `POST /api/hub/catalogs/{catalogId}/subscribe` cria uma assinatura ativa; `POST /api/hub/subscriptions/{subscriptionId}/sync` dispara atualização manual
* **Resolução de conflitos**: `GET /api/hub/subscriptions/{subscriptionId}/conflicts` lista conflitos de campo; `PATCH` resolve conflitos individuais com `keep_local`, `accept_remote` ou `manual_review`
* **Analytics do publisher**: `GET /api/hub/catalogs/{catalogId}/analytics` retorna contagem de assinantes, contagem de clones e tendências semanais de visualizações (até 90 dias)
* **Versionamento**: publicar uma nova versão de um catálogo assinado dispara webhooks `catalog.version.published` para todos os assinantes ativos

**Bright Data — Produção**

* Integração Bright Data promovida de beta para GA; API de cobrança real conectada (uso cobrado por crédito de scrape consumido)
* Webhooks de importação por URL: eventos `url_import.completed` e `url_import.failed` agora entregues com payload completo do produto no sucesso
* Endpoint de entrega de dataset: `POST /api/workspace/{workspaceId}/datasets/ingest` aceita payloads de datasets Bright Data diretamente

**DX de Distribuição**

* `llms.txt` publicado em `https://docs.alana.shopping/llms.txt` — resumo da plataforma legível por máquina para janelas de contexto de LLMs
* Feed API: streaming NDJSON agora suportado via cabeçalho `Accept: application/x-ndjson` em `GET /api/mcp/feed/{platform}`
* Catálogo unificado de erros: todos os erros da API agora incluem `error_code` (ex: `CATALOG_NOT_PUBLISHED`, `RATE_LIMIT_EXCEEDED`) — veja [Referência de Erros](/pt/api-reference/overview#error-codes)
* MCP Tools: filtragem de ferramentas via param `?tools=` no connect SSE — assine apenas as categorias de ferramenta que você precisa
* Quickstarts de plataforma adicionados para Shopify, WooCommerce e storefronts personalizados
* Webhooks de feed: `POST /api/v1/feeds/{platform}/webhooks` — registre endpoints para receber eventos `feed.updated`
* Analytics de feed: `GET /api/v1/feeds/{platform}/analytics` — métricas de consumo (requisições, taxa de cache hit, taxa de erro, principais consumidores)
* Coleção Postman publicada: importe via `https://docs.alana.shopping/postman.json`

***

### v1.8.0 — Integração Bright Data + Pipeline Bronze/Silver/Gold {/* 2026-03-10 */}

<Info>
  Esta versão introduz o pipeline de dados medallion ADR-015 e a integração Bright Data em produção para aquisição automatizada de dados de produtos.
</Info>

**Integração Bright Data**

* Cinco clientes Bright Data integrados: `ProductScraper`, `WebUnlocker`, `DatasetDelivery`, `ProxyManager`, `SearchScraper`
* Importação por URL: `POST /api/workspace/{workspaceId}/url-import/jobs` — envie uma URL de página de produto; Bright Data faz scraping e extrai dados estruturados
* Web scraping com bypass automático de CAPTCHA, rotação de proxy residencial e renderização JavaScript
* Polling assíncrono de status de job e entrega de webhook na conclusão

**Pipeline Bronze/Silver/Gold (ADR-015)**

* **Estágio Bronze**: ingestão bruta de produtos com chave de idempotência (`source_identifier`) — previne importações duplicadas da mesma fonte em execuções repetidas
* **Estágio Silver**: normalização de campos (mapeia nomes de colunas arbitrários para o schema Alana), detecção de duplicatas no catálogo, validação de URLs de imagem
* **Estágio Gold**: scoring de rubrica de otimização 7 dimensões (0–100) abrangendo identidade, conteúdo, mídia, precificação, disponibilidade, SEO e conformidade; retorna pontuação + lista de gaps por produto
* Estágios do pipeline executam automaticamente após importação (configurável) ou sob demanda via Ações em Lote

**UI de Ações em Lote**

* Novo painel de **Ações em Lote** na visualização de catálogo: execute normalização Silver ou scoring Gold em uma seleção ou catálogo inteiro
* Indicador de progresso em tempo real com atualizações de status por produto
* Resumo de erros com exportação de detalhe em nível de linha (CSV)

**Configurações do Pipeline**

* Novo painel de **Configurações do Pipeline** nas configurações do workspace:
  * **Mapeamentos Silver**: mapeie nomes de colunas personalizados para campos Alana padrão
  * **Pesos Gold**: ajuste os pesos da rubrica por dimensão (identidade, conteúdo, mídia, precificação, disponibilidade, SEO, conformidade)
  * **Auto-trigger**: configure se Silver executa automaticamente após Bronze, e se Gold executa após Silver

***

### v1.7.0 — Excelência em Distribuição {/* 2026-03-16 */}

<Warning>
  **Breaking change**: O parâmetro de query `?key=` para autenticação via chave de API foi removido de todos os endpoints do Canal 2 (Search API). Use exclusivamente o cabeçalho `x-api-key`.
</Warning>

**Canal 2 — Search API**

* **BREAKING**: parâmetro de query `?key=` removido de todos os endpoints `/api/v1/*`. Chaves de API devem ser passadas via cabeçalho de requisição `x-api-key`. Chaves em URLs são visíveis em logs, cabeçalhos Referer e histórico do navegador — esta mudança melhora a segurança para todos os consumidores da Search API.
  * **Migração**: substitua `GET /api/v1/search?key=ak_xxx` por `GET /api/v1/search` + cabeçalho `x-api-key: ak_xxx`.
  * Endpoints afetados: `/api/v1/search`, `/api/v1/autocomplete`, `/api/v1/browse`, `/api/v1/recommend`, `/api/v1/recommendations/*`, `/api/v1/events`, `/api/v1/analytics/*`, `/api/v1/serving-configs/*`, `/api/v1/facets/*`, `/api/v1/synonyms/*`, `/api/v1/boost-rules/*`, `/api/v1/language`, `/api/v1/pipeline/status`, `/api/v1/bandit/state`, `/api/v1/cache/metrics`

**Canal 1 — Feed API**

* Hardening de validação de entrada em `GET /api/mcp/feed/[platform]`:
  * Parâmetro `?q=`: caracteres de controle removidos, máximo de 500 caracteres aplicado (400 em violação)
  * Parâmetro `?catalog_id=`: formato UUID validado (400 em formato inválido)

**Canal 1 + Canal 3 — Depreciação de Chaves API Legadas**

* Respostas autenticadas com chaves API legadas agora incluem cabeçalhos de depreciação:
  * `X-Api-Key-Deprecated: true`
  * `X-Deprecation-Info: https://docs.alana.shopping/pt/authentication#m2m-migration`
  * `Deprecation: true` (RFC 8594)
* Migre para tokens Auth0 M2M: [veja o guia de migração](https://docs.alana.shopping/pt/authentication#m2m-migration)

**Rate Limiting + Observabilidade**

* Todas as respostas da API incluem `X-Request-Id` para rastreamento distribuído
* `X-Request-Id` ecoado do upstream quando o cliente o envia; gerado (UUID v4) caso contrário
* Canal 1: 60 req/min por chave API; 429 inclui `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `Retry-After`
* Canal 3: 200 req/min por chave + 50 req/min por chave+IP; aplicação em dois níveis

***

## Fevereiro de 2026

### v1.0.0 — Disponibilidade Geral {/* 2026-02-15 */}

<Info>
  Alana Shopping B2B v1.0 está no ar. Esta é a primeira versão de produção da plataforma.
</Info>

**Plataforma**

* Gerenciamento de workspace com RBAC completo (owner, admin, editor, viewer)
* Segurança em nível de linha em todos os recursos
* Assistente de onboarding com carregamento de dados de exemplo
* Suporte a domínio personalizado e branding de workspace
* Exportação de dados e exclusão de conta em conformidade com GDPR
* Registro de auditoria abrangente (mais de 38 tipos de ação)

**Motor de Catálogo**

* Criar, publicar, bifurcar e mesclar catálogos
* CRUD de produtos com pontuação de otimização (0–100)
* Validação de prontidão de feed para Google Shopping e Meta Commerce
* Importação em lote de arquivos CSV e Excel
* Endpoint público de feed de produtos para catálogos publicados

**Serviços de AI**

* Geração de conteúdo com consciência de marca via abstração LiteLLM
* Chat AI Canvas com RAG (especificações de marca + contexto de produto)
* Geração de texto para descrições, títulos e bullet points
* Aprimoramento de conteúdo com alinhamento de gramática, tom e palavras-chave
* Especificações de AI por marca: tom, palavras-chave, políticas, público

**Cobrança e Assinaturas**

* Quatro planos: Standard, Pro, Business, Enterprise
* Checkout, assinaturas e portal do cliente com Stripe
* Rastreamento de uso com alertas configuráveis
* Histórico de faturas e download em PDF

**Integrações**

* Conexões de plataforma baseadas em OAuth
* Sincronização bidirecional de produtos com plataformas de e-commerce
* Suporte ao protocolo MCP (batches de entrada, assinaturas de feed, busca)
* Integração de suporte ao cliente com Intercom

**Experiência do Desenvolvedor**

* API REST com mais de 90 endpoints e playground interativo
* Gerenciamento de chave de API com permissões granulares
* Paginação baseada em cursor em todos os endpoints de listagem
* Respostas de erro estruturadas com códigos de erro
* Endpoints de health e readiness para monitoramento

**Segurança**

* Supabase Auth com email/senha, magic links e OAuth
* Timeouts de sessão configuráveis e aplicação de 2FA
* Lista de permissão de IP para acesso à API
* Verificação de assinatura de webhook do Stripe
* Logout forçado em nível de workspace