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

# Concetti fondamentali

> Negozio, envelope, errori, paginazione, i18n e immagini.

## Base URL & identificazione del negozio

```
https://<dominio-del-negozio>/api/v1
```

Chiamando l'API attraverso il dominio del negozio ricevi **solo** i dati di quel negozio —
niente identificativo da inviare. Da un client senza dominio (mobile/server) usa la
[chiave publishable](/authentication).

## Envelope

Tutte le risposte JSON hanno la stessa busta:

```json theme={null}
{ "data": null, "meta": null, "error": null, "error_code": null }
```

## Errori

Sugli errori, `data` è `null` e `error_code` porta un codice macchina stabile. Il frontend
deve fare **switch su `error_code`**, non mostrare `error` (inglese, solo per debug).

```json theme={null}
{
  "data": null,
  "error": "Invalid credentials",
  "error_code": "auth.invalid_credentials"
}
```

Gli status HTTP seguono la semantica standard (200, 201, 400, 401, 403, 404, 409, 422, 502).

## Paginazione

Le liste accettano `page` e `page_size` e restituiscono `meta`:

```json theme={null}
{ "meta": { "page": 1, "page_size": 24, "total": 190, "total_pages": 8 } }
```

## Internazionalizzazione

Molti endpoint di contenuto accettano `?lang=it|en|sq` (o l'header `Accept-Language`) e
restituiscono i campi già risolti nella lingua richiesta, con fallback alla lingua di
default del negozio.

## Immagini

I percorsi immagine sono relativi (`/uploads/products/xyz.webp`): preponi l'origin del
negozio → `https://<dominio>/uploads/...`. In produzione sono servite via CDN/redirect
firmato, quindi usa l'URL così com'è restituito.

## Multi-tenant in breve

Ogni negozio è un **tenant** isolato. La chiave publishable e il dominio determinano il
tenant per le chiamate storefront; il claim `tenant_id` del token staff lo determina per la
Admin API. Non c'è modo, con credenziali di un negozio, di vedere i dati di un altro.