> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jelou.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Configurações da loja

> Configure a moeda, os impostos, o idioma e a disponibilidade de produtos da sua loja.

Permite configurar a moeda, a taxa de imposto, o idioma e outros ajustes globais da sua loja. Você pode enviar um ou vários campos na mesma solicitação.

**app\_id** `string` *required*

O ID da sua loja no Jelou Shop.

**currency** `string`

Código da moeda no formato [ISO 4217](https://pt.wikipedia.org/wiki/ISO_4217) (exatamente 3 caracteres). Exemplo: `USD`, `EUR`, `COP`, `MXN`.

**tax\_value** `number`

Taxa de imposto como valor decimal entre `0` e `1`. Exemplo: `0.15` para 15%, `0.19` para 19%.

**enable\_per\_product\_tax** `boolean`

Habilita a configuração de taxa de imposto individual por produto. Quando está ativo, cada produto pode ter sua própria taxa no campo `tax`. Se o produto não tiver taxa configurada, `tax_value` é usado como fallback.

**exclude\_out\_of\_stock** `boolean` (default: true)

Quando está ativo, os produtos sem estoque são excluídos por padrão dos resultados de busca. Se desativar, esses produtos continuarão aparecendo nas buscas.

**language** `string` (default: es)

Idioma padrão da loja. Afeta as mensagens localizadas devolvidas pela API (por exemplo, `friendly_message` nos endpoints de busca). Valores permitidos: `es`, `en`, `pt`.

**default\_order\_by** `string`

Ordenação padrão da listagem e da busca de produtos. Formato: `campo direção` (ex.: `price ASC`, `discount DESC`). Campos permitidos: `price`, `discount`, `discount_value`, `created_at`, `name`, `score`, `category_order`. Direções: `ASC` ou `DESC` (padrão `DESC`). Se não for configurado, ordena por `score DESC`. Envie `null` ou string vazia para redefinir.

**use\_v2\_search** `boolean`

Ativa o motor de busca V2 para a loja.

**search\_synonyms** `object`

Dicionário de sinônimos para a busca. Cada chave é um termo e seu valor é uma lista de sinônimos (cada um máx. 100 caracteres). Exemplo: `{ "celular": ["móvel", "smartphone"] }`. Envie `null` para removê-lo.

**search\_stop\_words** `string[]`

Lista de palavras que a busca ignora (stop words). Cada uma máx. 100 caracteres. Envie `null` para removê-la.

**search\_brands** `string[]`

Lista de marcas reconhecidas pela busca. Cada uma máx. 100 caracteres. Envie `null` para removê-la.

**show\_initial\_categories** `boolean`

Controla se a loja exibe um conjunto inicial de categorias (por exemplo, ao abrir a busca sem um termo).

```bash cURL theme={null}
curl -X PATCH "https://gateway.jelou.ai/ecommerce/v1/apps/{app_id}/settings" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "COP",
    "tax_value": 0.19,
    "enable_per_product_tax": true,
    "exclude_out_of_stock": true,
    "language": "pt"
  }'
```

```json 200 OK theme={null}
{
  "currency": "COP",
  "tax_value": 0.19,
  "exclude_out_of_stock": true,
  "enable_per_product_tax": true,
  "language": "pt",
  "default_order_by": "price ASC",
  "use_v2_search": true,
  "search_synonyms": { "celular": ["móvel", "smartphone"] },
  "search_stop_words": ["de", "a", "o"],
  "search_brands": ["Nike", "Adidas"],
  "show_initial_categories": true
}
```

## Moeda

A moeda padrão de toda loja é `USD`. Se você não configurou uma moeda, os preços serão exibidos em dólares americanos.

### Moedas comuns

| Código | Moeda |
| - | - |
| `USD` | Dólar americano |
| `EUR` | Euro |
| `COP` | Peso colombiano |
| `MXN` | Peso mexicano |
| `PEN` | Sol peruano |
| `CLP` | Peso chileno |
| `BRL` | Real brasileiro |
| `ARS` | Peso argentino |

## Imposto

Os preços armazenados no Jelou Shop **incluem imposto**. A taxa configurada é usada para **extrair** o imposto do preço bruto:

```
preço_líquido = preço / (1 + tax_value)
imposto       = preço - preço_líquido
```

**Exemplo:** Um produto com preço `$11.50` e taxa `0.15` (15%):

* Preço líquido: `$11.50 / 1.15 = $10.00`
* Imposto: `$11.50 - $10.00 = $1.50`

### Taxas padrão por moeda

Se você não configurar `tax_value`, um valor padrão será atribuído com base na moeda da loja:

| Moeda | Taxa padrão |
| - | - |
| `COP` | 19% (`0.19`) |
| `PEN` | 18% (`0.18`) |
| `MXN` | 16% (`0.16`) |
| Outras | 15% (`0.15`) |

## IVA por produto

Quando `enable_per_product_tax` está ativo, você pode atribuir uma taxa de imposto individual a cada produto usando o campo `tax` no [endpoint de produtos](https://docs.jelou.ai/pt/api/shop/produtos/upsert.md).

* Se o produto tem `tax > 0`, essa taxa é usada.
* Se o produto tem `tax = 0` ou não foi configurado, `tax_value` da loja é usado como fallback.
* Para produtos isentos de imposto, use `has_tax: false`.

A resposta do carrinho incluirá um detalhamento de impostos (`tax_breakdown`) agrupado por taxa quando esta opção está ativa.

## Disponibilidade de produtos

`exclude_out_of_stock` controla se os produtos sem estoque aparecem nos resultados de busca da loja:

* `true` (valor padrão): os produtos sem estoque são ocultados nos endpoints de busca.
* `false`: os produtos sem estoque continuam aparecendo. Útil quando você quer que os clientes vejam todo o catálogo mesmo que não haja inventário disponível.

Esta configuração só afeta o comportamento padrão das buscas. Os produtos com `stock_type = "unlimited"` são sempre considerados disponíveis.

## Idioma

`language` define o idioma padrão da loja e é usado para localizar as respostas da API.

| Valor | Idioma |
| - | - |
| `es` | Espanhol (valor padrão) |
| `en` | Inglês |
| `pt` | Português |

Atualmente afeta campos como `friendly_message` devolvidos pelos endpoints de busca (`multi_search`, `v2_search`). O valor enviado é normalizado para minúsculas.

> [!NOTE]
>
> Substitua `{app_id}` pelo ID da sua loja e `YOUR_API_KEY` pela sua [chave de API](https://docs.jelou.ai/pt/guias/configuracao/chaves-api.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.