Pular para o conteúdo principal

​
Métodos de importação

O Alana suporta múltiplos métodos de importação dependendo da sua fonte de dados:
MétodoComoMelhor para
CSV / ExcelUpload de arquivoCatálogo em massa de planilha
Importação de URLScraping via Bright DataExtrair dados de produto de uma URL
Shopify / WooCommerceConector de plataformaLoja de e-commerce existente
MCP inboundPush via API MCP por agente de IAPopulação de catálogo por agentes
Importação de datasetEntrega de dataset Bright DataAquisiçã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).

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

ColunaObrigatórioDescrição
titleSimNome do produto
skuSimUnidade de manutenção de estoque única
priceSimPreço de venda (numérico)
currencyNãoCódigo ISO 4217 (padrão para moeda do workspace)
descriptionNãoDescrição do produto
brandNãoNome da marca (deve existir no workspace)
categoryPathNãoHierarquia de categoria separada por >
primaryImageUrlNãoURL da imagem principal do produto
gtinNãoNúmero Global de Item Comercial
originalPriceNãoPreço original para exibição de desconto
availabilityNãoStatus de estoque (ex: “em estoque”, “fora de estoque”)
Colunas adicionais são armazenadas como attributes flexíveis.

​
Importar via API

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: 
{
  "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, ou configure auto-trigger em Configurações do Pipeline.

​
Melhores práticas

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.
Siga um formato de hierarquia consistente: Nível 1 > Nível 2 > Nível 3. Caminhos inconsistentes criam categorias duplicadas.
Produtos com GTINs pontuam mais alto em otimização e são obrigatórios para a maioria dos feeds de compras (Google, Meta).
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.
Last modified on March 18, 2026