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

<ParamField path="app_id" type="string" required>
  O ID da sua loja no Jelou Shop.
</ParamField>

<ParamField body="currency" type="string">
  Código da moeda no formato [ISO 4217](https://pt.wikipedia.org/wiki/ISO_4217) (exatamente 3 caracteres). Exemplo: `USD`, `EUR`, `COP`, `MXN`.
</ParamField>

<ParamField body="tax_value" type="number">
  Taxa de imposto como valor decimal entre `0` e `1`. Exemplo: `0.15` para 15%, `0.19` para 19%.
</ParamField>

<ParamField body="enable_per_product_tax" type="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.
</ParamField>

<ParamField body="exclude_out_of_stock" type="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.
</ParamField>

<ParamField body="language" type="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`.
</ParamField>

<ParamField body="default_order_by" type="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.
</ParamField>

<ParamField body="use_v2_search" type="boolean">
  Ativa o motor de busca V2 para a loja.
</ParamField>

<ParamField body="search_synonyms" type="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.
</ParamField>

<ParamField body="search_stop_words" type="string[]">
  Lista de palavras que a busca ignora (stop words). Cada uma máx. 100 caracteres. Envie `null` para removê-la.
</ParamField>

<ParamField body="search_brands" type="string[]">
  Lista de marcas reconhecidas pela busca. Cada uma máx. 100 caracteres. Envie `null` para removê-la.
</ParamField>

<ParamField body="show_initial_categories" type="boolean">
  Controla se a loja exibe um conjunto inicial de categorias (por exemplo, ao abrir a busca sem um termo).
</ParamField>

<RequestExample>
  ```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"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```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
  }
  ```
</ResponseExample>

## 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](/pt/guias/integracoes/e-commerce/api-productos/upsert).

* 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](/pt/guias/configuracao/chaves-api).
</Note>