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

# API de Configurações do Pipeline

> Endpoints GET e PUT para gerenciar configurações de pipeline do workspace — mapeamentos de campos Silver, pesos de scoring Gold e flags de comportamento.

## Endpoints

```
GET  /api/workspace/{workspaceId}/settings/pipeline
PUT  /api/workspace/{workspaceId}/settings/pipeline
```

Leia e atualize a configuração do pipeline a nível de workspace, incluindo mapeamentos de campos Silver, pesos de scoring Gold, comportamento de auto-trigger e modo de preview.

***

## Parâmetros de path

| Parâmetro     | Tipo   | Obrigatório | Descrição           |
| ------------- | ------ | :---------: | ------------------- |
| `workspaceId` | string |     Sim     | Seu ID de workspace |

***

## GET — Ler configurações

Retorna a configuração atual do pipeline para o workspace.

### Resposta

```json theme={null}
{
  "silverMappings": [
    {
      "sourceField": "product_name",
      "targetField": "title",
      "transform": "trim"
    }
  ],
  "goldWeights": {
    "identity": 20,
    "taxonomy": 15,
    "content": 25,
    "media": 20,
    "pricing": 10,
    "attributes": 5,
    "seo": 5
  },
  "autoTriggerSilver": false,
  "autoTriggerGold": false,
  "previewMode": false,
  "updatedAt": "2026-03-15T10:30:00Z"
}
```

***

## PUT — Atualizar configurações

Atualiza a configuração do pipeline. Todos os campos são opcionais — inclua apenas os campos que deseja alterar.

### Objeto FieldMapping

| Campo         | Tipo   | Obrigatório | Descrição                                                                                  |
| ------------- | ------ | :---------: | ------------------------------------------------------------------------------------------ |
| `sourceField` | string |     Sim     | Nome da coluna de origem como aparece no arquivo de importação                             |
| `targetField` | string |     Sim     | Campo de destino no schema do Alana                                                        |
| `transform`   | string |     Não     | Transformação opcional: `"trim"`, `"uppercase"`, `"lowercase"`, `"prefix:X"`, `"suffix:X"` |

### Flags de comportamento

| Campo               | 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 Silver concluir        |
| `previewMode`       | boolean | `false` | Simular mudanças no pipeline sem gravar nos produtos      |

<Warning>
  Todos os valores de `goldWeights` devem somar exatamente 100. Um erro 422 é retornado se a soma estiver incorreta.
</Warning>

***

## Exemplos

<CodeGroup>
  ```bash cURL theme={null}
  # Ler configurações atuais
  curl "https://app.alana.shopping/api/workspace/ws_123/settings/pipeline" \
    -H "Authorization: Bearer sk_live_sua_chave_api"

  # Atualizar mapeamentos Silver
  curl -X PUT "https://app.alana.shopping/api/workspace/ws_123/settings/pipeline" \
    -H "Authorization: Bearer sk_live_sua_chave_api" \
    -H "Content-Type: application/json" \
    -d '{
      "silverMappings": [
        { "sourceField": "product_name", "targetField": "title", "transform": "trim" },
        { "sourceField": "item_code", "targetField": "sku" }
      ]
    }'
  ```

  ```javascript JavaScript theme={null}
  // Ler
  const settings = await fetch(
    `https://app.alana.shopping/api/workspace/${workspaceId}/settings/pipeline`,
    { headers: { 'Authorization': `Bearer ${process.env.ALANA_API_KEY}` } }
  ).then(r => r.json());

  // Atualizar
  const updated = await fetch(
    `https://app.alana.shopping/api/workspace/${workspaceId}/settings/pipeline`,
    {
      method: 'PUT',
      headers: {
        'Authorization': `Bearer ${process.env.ALANA_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        silverMappings: [
          { sourceField: 'product_name', targetField: 'title', transform: 'trim' },
        ],
        autoTriggerSilver: true,
      }),
    }
  ).then(r => r.json());
  ```

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

  headers = {"Authorization": f"Bearer {os.environ['ALANA_API_KEY']}"}
  base = f"https://app.alana.shopping/api/workspace/{workspace_id}/settings/pipeline"

  # Ler
  settings = requests.get(base, headers=headers).json()
  print(f"Pesos Gold: {settings['goldWeights']}")

  # Atualizar
  updated = requests.put(base, headers=headers, json={
      "autoTriggerSilver": True,
      "autoTriggerGold": False,
  }).json()
  ```
</CodeGroup>

***

## Respostas de erro

| Status HTTP | Código                     | Descrição                                          |
| ----------- | -------------------------- | -------------------------------------------------- |
| 403         | `INSUFFICIENT_PERMISSIONS` | Chave API sem `settings:write`                     |
| 404         | `WORKSPACE_NOT_FOUND`      | ID de workspace não encontrado                     |
| 422         | `WEIGHTS_SUM_INVALID`      | Pesos Gold não somam 100                           |
| 422         | `VALIDATION_ERROR`         | Valor de mapeamento de campo ou transform inválido |