Pular para o conteúdo principal

​
Visão geral

As Configurações do Pipeline permitem personalizar como o pipeline Bronze → Silver → Gold se comporta no seu workspace. Você pode definir mapeamentos de campos personalizados (Silver), ajustar pesos de pontuação (Gold), habilitar auto-acionamentos e usar o modo preview para testar mudanças com segurança.

​
Acessando as configurações do pipeline

Via UI:
  1. Navegue até Configurações → Pipeline
  2. A página de configurações exibe abas para Mapeamentos Silver, Pesos Gold e Comportamento
Via API:
  • GET /api/workspace/{workspaceId}/settings/pipeline — ler configurações atuais
  • PUT /api/workspace/{workspaceId}/settings/pipeline — atualizar configurações
As configurações são aplicadas no nível do workspace e afetam todos os catálogos no workspace. Substituições no nível de equipe estão disponíveis nos planos Enterprise.

​
Mapeamentos de campos Silver

Os mapeamentos Silver definem como campos fonte não padrão são mapeados para o schema de produto da Alana.

​
Por que você precisa de mapeamentos

Quando os arquivos do fornecedor usam nomes de colunas como "codigo_item" em vez de "sku", ou "nome_prod" em vez de "title", o Silver não saberá como mapeá-los sem configuração explícita.

​
Regras de mapeamento

Cada regra de mapeamento tem:
PropriedadeTipoDescrição
sourceFieldstringO nome da coluna como aparece no arquivo fonte
targetFieldstringO campo do schema Alana para mapear
transformstring (opcional)Transformação a aplicar: "uppercase", "lowercase", "trim", "prefix:X", "suffix:X"

​
Exemplo de mapeamentos

{
  "silverMappings": [
    {
      "sourceField": "nome_produto",
      "targetField": "title",
      "transform": "trim"
    },
    {
      "sourceField": "codigo_item",
      "targetField": "sku"
    },
    {
      "sourceField": "cat",
      "targetField": "categoryPath",
      "transform": "prefix:Roupas > "
    },
    {
      "sourceField": "fornecedor",
      "targetField": "brand"
    }
  ]
}

​
Campos alvo disponíveis

Campo alvoTipoDescrição
titlestringNome do produto
skustringCódigo de estoque
gtinstringNúmero Global de Item Comercial
pricenumberPreço de venda
originalPricenumberPreço antes do desconto
currencystringCódigo ISO 4217
brandstringNome da marca
categoryPathstringHierarquia de categoria (separada por >)
descriptionstringDescrição completa do produto
shortDescriptionstringDescrição breve
primaryImageUrlstringURL da imagem principal
availabilitystringStatus de estoque

​
Pesos de pontuação Gold

Os pesos Gold definem a importância de cada um dos 7 estágios de pontuação. Todos os pesos devem somar 100.

​
Pesos padrão

EstágioPeso padrão
Identidade (SKU, GTIN, marca)20%
Taxonomia (profundidade de categoria)15%
Conteúdo (título, descrição, bullet points)25%
Mídia (imagens, vídeo)20%
Precificação (preço, moeda, original)10%
Atributos (especificações específicas da categoria)5%
SEO (slug, meta, palavras-chave)5%

​
Exemplo de peso personalizado

Para um catálogo focado em mídia (ex.: fotografia de moda): 
{
  "goldWeights": {
    "identity": 15,
    "taxonomy": 10,
    "content": 20,
    "media": 35,
    "pricing": 10,
    "attributes": 5,
    "seo": 5
  }
}
Todos os valores de peso devem somar exatamente 100. A API retorna um erro 422 se a soma estiver incorreta.

​
Configurações de comportamento

ConfiguraçãoTipoPadrãoDescrição
autoTriggerSilverbooleanfalseExecutar Silver automaticamente após cada ingestão Bronze
autoTriggerGoldbooleanfalseExecutar Gold automaticamente após a conclusão do Silver
previewModebooleanfalseSimular mudanças no pipeline sem gravar nos produtos
autoTriggerGold: true não é recomendado para catálogos grandes. A pontuação Gold tem um custo e pode ser lenta para mais de 10.000 produtos. Use acionamento manual ou agendado.

​
Modo preview

Quando previewMode: true, as operações do pipeline simulam transformações e retornam o que aconteceria — sem modificar nenhum registro de produto. Use o modo preview para:
  • Testar um novo mapeamento Silver antes de aplicá-lo a dados reais
  • Ver como novos pesos Gold afetariam as pontuações
  • Validar a lógica de mapeamento de campos sem risco

​
Exemplo de resposta preview (Silver)

{
  "preview": true,
  "results": [
    {
      "productId": "prod_abc",
      "status": "would_succeed",
      "fieldsWouldNormalize": ["title", "categoryPath", "brand"],
      "currentValues": {
        "title": "tenis running azul",
        "categoryPath": "calcados"
      },
      "newValues": {
        "title": "Tênis Running Azul",
        "categoryPath": "Roupas > Calçados > Running"
      }
    }
  ]
}

​
Ler configurações atuais

curl "https://app.alana.shopping/api/workspace/WORKSPACE_ID/settings/pipeline" \
  -H "Authorization: Bearer SUA_API_KEY"

​
Atualizar configurações

curl -X PUT "https://app.alana.shopping/api/workspace/WORKSPACE_ID/settings/pipeline" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "silverMappings": [
      { "sourceField": "nome_produto", "targetField": "title" },
      { "sourceField": "codigo_item", "targetField": "sku" }
    ],
    "goldWeights": {
      "identity": 20,
      "taxonomy": 15,
      "content": 25,
      "media": 20,
      "pricing": 10,
      "attributes": 5,
      "seo": 5
    },
    "autoTriggerSilver": true,
    "autoTriggerGold": false,
    "previewMode": false
  }'

​
Coerência de pontuações

As pontuações Gold são recalculadas somente quando o Gold é acionado. Se você alterar goldWeights, as pontuações existentes nos produtos ficam desatualizadas até que o Gold seja executado novamente. Um banner na UI avisa quando as configurações foram alteradas desde a última execução de pontuação. Para atualizar pontuações após alterar pesos: 
# Execute novamente o Gold em todos os produtos após atualizar os pesos
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"}'

​
Boas práticas

Se os arquivos do fornecedor usam nomes de colunas não padrão, configure os mapeamentos Silver antes de importar. Isso garante que o primeiro import chegue corretamente sem precisar de reimport.
Antes de aplicar novos mapeamentos a um catálogo ativo, habilite o modo preview e execute o Silver em uma pequena seleção. Revise a saída de newValues para confirmar que os mapeamentos se comportam como esperado.
Após atualizar os pesos Gold, acione uma reanálise completa do catálogo para que todas as pontuações de produtos reflitam a nova configuração.
Se você tem um job de import recorrente (feed diário de fornecedor, CSV noturno), habilite autoTriggerSilver: true para que os produtos importados sejam normalizados automaticamente.
Last modified on March 18, 2026