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

# Enriquecimento de Dados

> Guia completo para enriquecer dados de produtos pelo pipeline Bronze → Silver → Gold, incluindo web scraping via Bright Data e análise SERP.

## Visão geral

O enriquecimento de dados é o processo de pegar registros brutos de produtos e melhorar progressivamente sua qualidade pelos estágios do pipeline. Este guia cobre o fluxo completo — desde o import inicial pelo Bronze, normalização Silver, pontuação Gold — até o enriquecimento avançado via web scraping com Bright Data.

***

## Passo 1 — Import (Bronze)

O primeiro passo é colocar seus dados no sistema. Todos os imports chegam na camada **Bronze**: brutos, sem modificação e idempotentes.

### Métodos de import

| Método                                                                  | Melhor para                                                  |
| ----------------------------------------------------------------------- | ------------------------------------------------------------ |
| Upload CSV/Excel                                                        | Planilhas de fornecedores existentes                         |
| Import por URL                                                          | Raspar páginas de produto diretamente da web                 |
| API (`POST /api/workspace/{workspaceId}/catalogs/{catalogId}/products`) | Feeds programáticos                                          |
| Feed MCP                                                                | Sincronização de catálogo em tempo real de sistemas externos |

Após o import, produtos ficam visíveis no catálogo com `pipeline_stage: "bronze"`.

***

## Passo 2 — Silver (Normalizar)

O Silver limpa e normaliza seus dados brutos: padroniza capitalização, valida URLs de imagens, detecta duplicatas e mapeia campos para o schema da Alana.

### Executar Silver via UI

1. Abra seu catálogo
2. Selecione os produtos que deseja normalizar (ou use **Selecionar Todos**)
3. Clique em **Ações em Lote** → **Normalizar**
4. Um indicador de progresso exibe normalizado / total
5. Quando concluído, revise o painel de resultados: campos mapeados, duplicatas encontradas, URLs quebradas

### Executar Silver via API

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST "https://app.alana.shopping/api/workspace/WORKSPACE_ID/catalogs/CATALOG_ID/batch/silver" \
    -H "Authorization: Bearer SUA_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"scope": "all"}'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    `https://app.alana.shopping/api/workspace/${workspaceId}/catalogs/${catalogId}/batch/silver`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ scope: 'all' }),
    }
  );
  const result = await response.json();
  console.log(`${result.processed} produtos normalizados em ${result.duration_ms}ms`);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      f"https://app.alana.shopping/api/workspace/{workspace_id}/catalogs/{catalog_id}/batch/silver",
      headers={"Authorization": f"Bearer {api_key}"},
      json={"scope": "all"}
  )
  result = response.json()
  print(f"{result['processed']} produtos normalizados em {result['duration_ms']}ms")
  ```
</CodeGroup>

### Resultados do Silver

Após o Silver, cada produto contém:

* `fieldsNormalized` — quantidade de campos transformados
* `duplicateOf` — ID do produto se uma duplicata foi detectada
* `urlsValidated` — quantidade de URLs de imagens/mídia verificadas
* `pipeline_stage: "silver"`

***

## Passo 3 — Gold (Pontuar & Analisar)

O Gold produz uma pontuação de otimização (0–100) e uma lista de lacunas — os campos que, se preenchidos, mais aumentariam a pontuação.

### Executar Gold via UI

1. Selecione produtos no catálogo
2. Clique em **Ações em Lote** → **Analisar**
3. Um indicador de progresso exibe analisados / total
4. Quando concluído, cada produto exibe seu badge de pontuação e destaques de lacunas

### Executar Gold via API

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST "https://app.alana.shopping/api/workspace/WORKSPACE_ID/catalogs/CATALOG_ID/batch/gold" \
    -H "Authorization: Bearer SUA_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"scope": "all"}'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    `https://app.alana.shopping/api/workspace/${workspaceId}/catalogs/${catalogId}/batch/gold`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ scope: 'all' }),
    }
  );
  const { results, catalogSummary } = await response.json();
  console.log(`Pontuação média: ${catalogSummary.avgScore}`);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      f"https://app.alana.shopping/api/workspace/{workspace_id}/catalogs/{catalog_id}/batch/gold",
      headers={"Authorization": f"Bearer {api_key}"},
      json={"scope": "all"}
  )
  data = response.json()
  print(f"Pontuação média: {data['catalogSummary']['avgScore']}")
  ```
</CodeGroup>

***

## Passo 4 — Revisar pontuações no Canvas

Após o Gold, abra o **Canvas** para revisar e agir sobre os resultados do enriquecimento:

1. Ordene produtos por pontuação (crescente) para encontrar os itens de menor qualidade
2. Para cada produto, o painel **Lacunas** mostra exatamente quais campos estão ausentes
3. Use o editor inline para preencher lacunas diretamente no Canvas
4. Execute novamente o Gold nos produtos editados para atualizar a pontuação

***

## Passo 5 — Enriquecimento via Bright Data

Para produtos com dados incompletos, a Alana integra com o **Bright Data** para enriquecer via web scraping, análise SERP e presets de datasets.

### Import por URL com web scraping

Ao importar via URL de produto, o Web Scraper do Bright Data extrai dados estruturados diretamente da página do produto.

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST "https://app.alana.shopping/api/workspace/WORKSPACE_ID/url-import" \
    -H "Authorization: Bearer SUA_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "url": "https://example.com/produto/tenis-running-azul",
      "catalogId": "CATALOG_ID",
      "method": "web_scraper"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    `https://app.alana.shopping/api/workspace/${workspaceId}/url-import`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        url: 'https://example.com/produto/tenis-running-azul',
        catalogId,
        method: 'web_scraper',
      }),
    }
  );
  const { jobId } = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      f"https://app.alana.shopping/api/workspace/{workspace_id}/url-import",
      headers={"Authorization": f"Bearer {api_key}"},
      json={
          "url": "https://example.com/produto/tenis-running-azul",
          "catalogId": catalog_id,
          "method": "web_scraper",
      }
  )
  job = response.json()
  print(f"Job ID: {job['jobId']}")
  ```
</CodeGroup>

### Análise SERP para SEO

Use a API SERP do Bright Data para descobrir palavras-chave de alto valor para seus produtos. Os resultados são usados para otimizar títulos, descrições e campos meta durante a pontuação Gold.

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST "https://app.alana.shopping/api/workspace/WORKSPACE_ID/catalogs/CATALOG_ID/enrich/serp" \
    -H "Authorization: Bearer SUA_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "productIds": ["prod_123", "prod_456"],
      "locale": "pt-BR"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    `https://app.alana.shopping/api/workspace/${workspaceId}/catalogs/${catalogId}/enrich/serp`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        productIds: ['prod_123', 'prod_456'],
        locale: 'pt-BR',
      }),
    }
  );
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      f"https://app.alana.shopping/api/workspace/{workspace_id}/catalogs/{catalog_id}/enrich/serp",
      headers={"Authorization": f"Bearer {api_key}"},
      json={
          "productIds": ["prod_123", "prod_456"],
          "locale": "pt-BR",
      }
  )
  ```
</CodeGroup>

### Presets de datasets para análise competitiva

Os presets de datasets do Bright Data extraem dados estruturados de concorrentes por categorias como eletrônicos, roupas e produtos domésticos — úteis para comparar seu catálogo com os líderes de mercado.

Presets disponíveis:

* `electronics_specs` — especificações técnicas de grandes varejistas
* `apparel_sizing` — tabelas de tamanho e dados de caimento
* `grocery_nutrition` — informações nutricionais e ingredientes
* `home_goods_dimensions` — dimensões físicas e materiais

***

## Fluxo completo de enriquecimento

```mermaid theme={null}
graph LR
    A["URL / Arquivo Bruto"] --> B["Ingestão Bronze"]
    B --> C["Silver Normalizar\n(botão Normalizar)"]
    C --> D["Gold Analisar\n(botão Analisar)"]
    D --> E["Revisar Pontuações\nno Canvas"]
    E --> F{Lacunas?}
    F -- sim --> G["Preencher lacunas\n(edição inline / Bright Data)"]
    G --> D
    F -- não --> H["Publicar / Distribuir"]
```

***

## Boas práticas

<AccordionGroup>
  <Accordion title="Sempre execute o Silver antes do Gold">
    A pontuação Gold depende de dados normalizados. Executar Gold em dados Bronze brutos produz pontuações artificialmente baixas porque campos como marca e categoria ainda não estão vinculados.
  </Accordion>

  <Accordion title="Use enriquecimento SERP para produtos prioritários">
    A análise SERP tem um custo por consulta. Execute-a nos SKUs de maior tráfego ou novos lançamentos de produtos, não em catálogos inteiros.
  </Accordion>

  <Accordion title="Priorize lacunas por impacto na pontuação">
    A lista de lacunas é ordenada por impacto. Preencher a primeira lacuna aumentará mais a pontuação do que preencher a última. Foque nas 2–3 primeiras lacunas por produto.
  </Accordion>

  <Accordion title="Execute o Gold novamente após cada sessão de edição">
    As pontuações não são ao vivo — elas refletem a última vez que o Gold foi executado. Execute o Gold novamente após preencher lacunas para obter pontuações atualizadas.
  </Accordion>
</AccordionGroup>