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

# Importação de Produtos

> Importe produtos em massa de arquivos CSV ou Excel.

## Métodos de importação

O Alana suporta múltiplos métodos de importação dependendo da sua fonte de dados:

| Método                    | Como                              | Melhor para                         |
| ------------------------- | --------------------------------- | ----------------------------------- |
| **CSV / Excel**           | Upload de arquivo                 | Catálogo em massa de planilha       |
| **Importação de URL**     | Scraping via Bright Data          | Extrair dados de produto de uma URL |
| **Shopify / WooCommerce** | Conector de plataforma            | Loja de e-commerce existente        |
| **MCP inbound**           | Push via API MCP por agente de IA | População de catálogo por agentes   |
| **Importação de dataset** | Entrega de dataset Bright Data    | Aquisição de dados em grande escala |

Após qualquer importação, o **estágio Bronze executa automaticamente** — produtos são ingeridos com chave de idempotência para prevenir duplicatas. A normalização Silver e o scoring Gold executam sob demanda ou via auto-trigger (configurável em [Configurações do Pipeline](/guides/pipeline-settings)).

## Importação por URL (Bright Data)

Importe produtos fornecendo uma URL de página de produto. O Bright Data faz scraping da página e extrai dados estruturados do produto.

```bash theme={null}
curl -X POST "https://app.alana.shopping/api/workspace/{workspaceId}/url-import/jobs" \
  -H "Authorization: Bearer SUA_CHAVE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/products/meu-produto",
    "catalogId": "CATALOG_ID"
  }'
```

Veja o guia de [Importação por URL](/guides/url-import) para detalhes sobre gerenciamento de jobs e notificações via webhook.

## Formatos de arquivo suportados

O endpoint de importação CSV/Excel aceita:

* **CSV** (`.csv`) — separado por vírgula ou ponto e vírgula
* **Excel** (`.xlsx`) — primeira planilha é usada

## Colunas obrigatórias

| Coluna            | Obrigatório | Descrição                                               |
| ----------------- | :---------: | ------------------------------------------------------- |
| `title`           |     Sim     | Nome do produto                                         |
| `sku`             |     Sim     | Unidade de manutenção de estoque única                  |
| `price`           |     Sim     | Preço de venda (numérico)                               |
| `currency`        |     Não     | Código ISO 4217 (padrão para moeda do workspace)        |
| `description`     |     Não     | Descrição do produto                                    |
| `brand`           |     Não     | Nome da marca (deve existir no workspace)               |
| `categoryPath`    |     Não     | Hierarquia de categoria separada por `>`                |
| `primaryImageUrl` |     Não     | URL da imagem principal do produto                      |
| `gtin`            |     Não     | Número Global de Item Comercial                         |
| `originalPrice`   |     Não     | Preço original para exibição de desconto                |
| `availability`    |     Não     | Status de estoque (ex: "em estoque", "fora de estoque") |

Colunas adicionais são armazenadas como `attributes` flexíveis.

## Importar via API

```bash theme={null}
curl -X POST ".../catalog/products/import" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@products.csv" \
  -F "catalogId=CATALOG_ID"
```

## Resposta da importação

A importação retorna um resumo:

```json theme={null}
{
  "total": 500,
  "created": 487,
  "errors": 13,
  "errorDetails": [
    {"row": 45, "field": "price", "message": "Formato de número inválido"},
    {"row": 112, "field": "sku", "message": "SKU duplicado: PROD-112"}
  ]
}
```

## Processamento automático pelo pipeline após importação

Quando produtos são importados, o pipeline Bronze → Silver → Gold os processa automaticamente (se configurado) ou sob demanda:

1. **Bronze** — produto bruto armazenado com chave de idempotência; importações duplicadas são ignoradas com segurança
2. **Silver** — campos normalizados, duplicatas detectadas, URLs de imagem validadas
3. **Gold** — pontuação de otimização (0–100) calculada em 7 estágios da rubrica; lista de gaps retornada

Acione Silver e Gold em massa via [Ações em Lote](/guides/batch-actions), ou configure auto-trigger em [Configurações do Pipeline](/guides/pipeline-settings).

## Melhores práticas

<AccordionGroup>
  <Accordion title="Valide antes de importar">
    Use um arquivo de teste pequeno (10-20 linhas) antes de importar seu catálogo completo. Verifique os detalhes de erro para corrigir problemas de formatação.
  </Accordion>

  <Accordion title="Use caminhos de categoria consistentes">
    Siga um formato de hierarquia consistente: `Nível 1 > Nível 2 > Nível 3`. Caminhos inconsistentes criam categorias duplicadas.
  </Accordion>

  <Accordion title="Inclua GTINs quando possível">
    Produtos com GTINs pontuam mais alto em otimização e são obrigatórios para a maioria dos feeds de compras (Google, Meta).
  </Accordion>

  <Accordion title="Execute Silver + Gold após importação">
    Após importar, execute Lote Silver para normalizar campos, depois Lote Gold para calcular pontuações de otimização. Isso fornece uma linha de base de qualidade antes de publicar. Veja [Enriquecimento de Dados](/guides/data-enrichment).
  </Accordion>
</AccordionGroup>