Configurações do Pipeline

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:

Navegue até Configurações → Pipeline
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:

Propriedade	Tipo	Descrição
`sourceField`	string	O nome da coluna como aparece no arquivo fonte
`targetField`	string	O campo do schema Alana para mapear
`transform`	string (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 alvo	Tipo	Descrição
`title`	string	Nome do produto
`sku`	string	Código de estoque
`gtin`	string	Número Global de Item Comercial
`price`	number	Preço de venda
`originalPrice`	number	Preço antes do desconto
`currency`	string	Código ISO 4217
`brand`	string	Nome da marca
`categoryPath`	string	Hierarquia de categoria (separada por `>`)
`description`	string	Descrição completa do produto
`shortDescription`	string	Descrição breve
`primaryImageUrl`	string	URL da imagem principal
`availability`	string	Status 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ágio	Peso 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ção	Tipo	Padrão	Descrição
`autoTriggerSilver`	boolean	`false`	Executar Silver automaticamente após cada ingestão Bronze
`autoTriggerGold`	boolean	`false`	Executar Gold automaticamente após a conclusão do Silver
`previewMode`	boolean	`false`	Simular 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"

const response = await fetch(
  `https://app.alana.shopping/api/workspace/${workspaceId}/settings/pipeline`,
  { headers: { 'Authorization': `Bearer ${apiKey}` } }
);
const settings = await response.json();
console.log('Pesos Gold atuais:', settings.goldWeights);

import requests

response = requests.get(
    f"https://app.alana.shopping/api/workspace/{workspace_id}/settings/pipeline",
    headers={"Authorization": f"Bearer {api_key}"}
)
settings = response.json()
print("Mapeamentos Silver atuais:", settings["silverMappings"])

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
  }'

const response = await fetch(
  `https://app.alana.shopping/api/workspace/${workspaceId}/settings/pipeline`,
  {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      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,
    }),
  }
);
const updated = await response.json();

import requests

response = requests.put(
    f"https://app.alana.shopping/api/workspace/{workspace_id}/settings/pipeline",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "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,
    }
)
updated = response.json()
print("Configurações atualizadas:", updated)

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

Configure mapeamentos antes do primeiro import

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.

Use o modo preview para mudanças de mapeamento

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.

Execute o Gold novamente após alterar os pesos

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.

Habilite autoTriggerSilver para feeds automatizados

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.

Primeiros Passos

Conceitos Fundamentais

Guias

Visão geral

Acessando as configurações do pipeline

Mapeamentos de campos Silver

Por que você precisa de mapeamentos

Regras de mapeamento

Exemplo de mapeamentos

Campos alvo disponíveis

Pesos de pontuação Gold

Pesos padrão

Exemplo de peso personalizado

Configurações de comportamento

Modo preview

Exemplo de resposta preview (Silver)

Ler configurações atuais

Atualizar configurações

Coerência de pontuações

Boas práticas

​Visão geral

​Acessando as configurações do pipeline

​Mapeamentos de campos Silver

​Por que você precisa de mapeamentos

​Regras de mapeamento

​Exemplo de mapeamentos

​Campos alvo disponíveis

​Pesos de pontuação Gold

​Pesos padrão

​Exemplo de peso personalizado

​Configurações de comportamento

​Modo preview

​Exemplo de resposta preview (Silver)

​Ler configurações atuais

​Atualizar configurações

​Coerência de pontuações

​Boas práticas

Visão geral

Acessando as configurações do pipeline

Mapeamentos de campos Silver

Por que você precisa de mapeamentos

Regras de mapeamento

Exemplo de mapeamentos

Campos alvo disponíveis

Pesos de pontuação Gold

Pesos padrão

Exemplo de peso personalizado

Configurações de comportamento

Modo preview

Exemplo de resposta preview (Silver)

Ler configurações atuais

Atualizar configurações

Coerência de pontuações

Boas práticas