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

# Configuración de tienda

> Configura la moneda, impuestos, idioma y disponibilidad de productos de tu tienda.

Permite configurar la moneda, la tasa de impuesto, el idioma y otros ajustes globales de tu tienda. Puedes enviar uno o varios campos en la misma solicitud.

<ParamField path="app_id" type="string" required>
  ID de tu tienda en Jelou Shop.
</ParamField>

<ParamField body="currency" type="string">
  Código de moneda en formato [ISO 4217](https://es.wikipedia.org/wiki/ISO_4217) (exactamente 3 caracteres). Ejemplo: `USD`, `EUR`, `COP`, `MXN`.
</ParamField>

<ParamField body="tax_value" type="number">
  Tasa de impuesto como valor decimal entre `0` y `1`. Ejemplo: `0.15` para 15%, `0.19` para 19%.
</ParamField>

<ParamField body="enable_per_product_tax" type="boolean">
  Habilita la configuración de tasa de impuesto individual por producto. Cuando está activo, cada producto puede tener su propia tasa en el campo `tax`. Si el producto no tiene tasa configurada, se usa `tax_value` como fallback.
</ParamField>

<ParamField body="exclude_out_of_stock" type="boolean" default="true">
  Cuando está activo, los productos sin stock se excluyen por defecto de los resultados de búsqueda. Si lo desactivas, esos productos seguirán apareciendo en las búsquedas.
</ParamField>

<ParamField body="language" type="string" default="es">
  Idioma predeterminado de la tienda. Afecta los mensajes localizados que devuelve la API (por ejemplo, `friendly_message` en los endpoints de búsqueda). Valores permitidos: `es`, `en`, `pt`.
</ParamField>

<ParamField body="default_order_by" type="string">
  Ordenamiento por defecto del listado y la búsqueda de productos. Formato: `campo dirección` (ej. `price ASC`, `discount DESC`). Campos permitidos: `price`, `discount`, `discount_value`, `created_at`, `name`, `score`, `category_order`. Direcciones: `ASC` o `DESC` (por defecto `DESC`). Si no se configura, se ordena por `score DESC`. Envía `null` o cadena vacía para restablecerlo.
</ParamField>

<ParamField body="use_v2_search" type="boolean">
  Activa el motor de búsqueda V2 para la tienda.
</ParamField>

<ParamField body="search_synonyms" type="object">
  Diccionario de sinónimos para la búsqueda. Cada clave es un término y su valor es una lista de sinónimos (cada uno máx. 100 caracteres). Ejemplo: `{ "celular": ["móvil", "smartphone"] }`. Envía `null` para eliminarlo.
</ParamField>

<ParamField body="search_stop_words" type="string[]">
  Lista de palabras que la búsqueda ignora (stop words). Cada una máx. 100 caracteres. Envía `null` para eliminarla.
</ParamField>

<ParamField body="search_brands" type="string[]">
  Lista de marcas reconocidas por la búsqueda. Cada una máx. 100 caracteres. Envía `null` para eliminarla.
</ParamField>

<ParamField body="show_initial_categories" type="boolean">
  Controla si la tienda muestra un conjunto inicial de categorías (por ejemplo, al abrir la búsqueda sin un término).
</ParamField>

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

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "currency": "COP",
    "tax_value": 0.19,
    "exclude_out_of_stock": true,
    "enable_per_product_tax": true,
    "language": "es",
    "default_order_by": "price ASC",
    "use_v2_search": true,
    "search_synonyms": { "celular": ["móvil", "smartphone"] },
    "search_stop_words": ["de", "la", "el"],
    "search_brands": ["Nike", "Adidas"],
    "show_initial_categories": true
  }
  ```
</ResponseExample>

## Moneda

La moneda predeterminada de toda tienda es `USD`. Si no has configurado una moneda, los precios se mostrarán en dólares americanos.

### Monedas comunes

| Código | Moneda               |
| ------ | -------------------- |
| `USD`  | Dólar estadounidense |
| `EUR`  | Euro                 |
| `COP`  | Peso colombiano      |
| `MXN`  | Peso mexicano        |
| `PEN`  | Sol peruano          |
| `CLP`  | Peso chileno         |
| `BRL`  | Real brasileño       |
| `ARS`  | Peso argentino       |

## Impuesto

Los precios almacenados en Jelou Shop **incluyen impuesto**. La tasa configurada se utiliza para **extraer** el impuesto del precio bruto:

```
precio_neto = precio / (1 + tax_value)
impuesto    = precio - precio_neto
```

**Ejemplo:** Un producto con precio `$11.50` y tasa `0.15` (15%):

* Precio neto: `$11.50 / 1.15 = $10.00`
* Impuesto: `$11.50 - $10.00 = $1.50`

### Tasas predeterminadas por moneda

Si no configuras `tax_value`, se asigna un valor predeterminado según la moneda de la tienda:

| Moneda | Tasa predeterminada |
| ------ | ------------------- |
| `COP`  | 19% (`0.19`)        |
| `PEN`  | 18% (`0.18`)        |
| `MXN`  | 16% (`0.16`)        |
| Otras  | 15% (`0.15`)        |

## IVA por producto

Cuando `enable_per_product_tax` está activo, puedes asignar una tasa de impuesto individual a cada producto usando el campo `tax` en el [endpoint de productos](/guides/integraciones/e-commerce/api-productos/upsert).

* Si el producto tiene `tax > 0`, se usa esa tasa.
* Si el producto tiene `tax = 0` o no se ha configurado, se usa `tax_value` de la tienda como fallback.
* Para productos exentos de impuesto, usa `has_tax: false`.

La respuesta del carrito incluirá un desglose de impuestos (`tax_breakdown`) agrupado por tasa cuando esta opción está activa.

## Disponibilidad de productos

`exclude_out_of_stock` controla si los productos sin stock aparecen en los resultados de búsqueda de la tienda:

* `true` (valor por defecto): los productos sin stock no se muestran en los endpoints de búsqueda.
* `false`: los productos sin stock siguen apareciendo. Útil cuando quieres que los clientes vean todo el catálogo aunque no haya inventario disponible.

Esta configuración solo afecta el comportamiento por defecto de las búsquedas. Los productos con `stock_type = "unlimited"` se consideran siempre disponibles.

## Idioma

`language` define el idioma predeterminado de la tienda y se utiliza para localizar las respuestas de la API.

| Valor | Idioma                      |
| ----- | --------------------------- |
| `es`  | Español (valor por defecto) |
| `en`  | Inglés                      |
| `pt`  | Portugués                   |

Actualmente afecta a campos como `friendly_message` devueltos por los endpoints de búsqueda (`multi_search`, `v2_search`). El valor enviado se normaliza a minúsculas.

<Note>
  Reemplaza `{app_id}` con el ID de tu tienda y `TU_CLAVE_API` con tu [clave API](/guides/configuracion/claves-api).
</Note>