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

# Costruisci uno storefront

> Catalogo → carrello → checkout → ordine, con la Storefront API.

Questa guida mostra il flusso principale di uno storefront. Tutti gli endpoint sono sotto
`/api/v1` e usano la [chiave publishable](/authentication) (o il dominio del negozio).

## 1. Catalogo & ricerca

```bash theme={null}
# lista prodotti con filtri
curl "$BASE/api/v1/products?category_id=<id>&min_price=500&sort=-created_at&page=1&page_size=24"
# dettaglio per slug
curl "$BASE/api/v1/products/<slug>?lang=it"
# ricerca full-text con facet
curl "$BASE/api/v1/search?q=iphone&page=1"
# categorie (albero), brand
curl "$BASE/api/v1/categories?tree=true"
```

## 2. Carrello

Il carrello funziona per ospiti (con un id/token di sessione) e per clienti loggati.

```bash theme={null}
# crea/aggiorna carrello, aggiungi una variante
curl -X POST "$BASE/api/v1/cart/items" -H "Content-Type: application/json" \
  -d '{"variant_id":"<id>","quantity":1}'
# leggi il carrello (totali, spedizione stimata)
curl "$BASE/api/v1/cart"
```

<Note>
  **Carrello cross-origin / headless.** Il carrello ospite è legato a un token di sessione,
  restituito nel campo `session_token` della risposta. Se il tuo storefront gira su un dominio
  diverso dall'API (es. `xxxx.com` → `api.vellaro.io`), il cookie `cx_cart` (`SameSite=Lax`) non
  viaggia cross-site: **salva `session_token` lato client** (es. `localStorage`) e rimandalo su
  **ogni** chiamata al carrello e al checkout come header **`X-Cart-Token`**. Così il carrello
  persiste ovunque e si **ripristina** al ritorno (TTL 7 giorni). Se sei same-origin, basta il
  cookie e l'header è opzionale.
</Note>

```bash theme={null}
# la risposta contiene { "data": { "session_token": "…", "items": [...] } }
# → salva session_token e rimandalo su ogni chiamata carrello + checkout:
curl -X POST "$BASE/api/v1/cart/items" \
  -H "X-Vellaro-Key: cx_pk_live_<slug>_..." \
  -H "X-Cart-Token: <session_token>" \
  -H "Content-Type: application/json" \
  -d '{"variant_id":"<id>","quantity":1}'
```

## 3. Checkout & pagamento

```bash theme={null}
# metodi di pagamento disponibili per il negozio
curl "$BASE/api/v1/settings/payment-methods"
# crea l'ordine
curl -X POST "$BASE/api/v1/checkout" -H "Content-Type: application/json" \
  -d '{ "email":"cliente@example.com", "shipping_address": { ... }, "payment_method":"stripe" }'
```

La risposta di checkout indica il **flusso di pagamento** (Stripe, PayPal, PokPay, Paysera,
contrassegno, bonifico): alcuni restituiscono un `client_secret`/redirect da completare
lato client, altri confermano subito. Vedi la [API Reference](/api-reference) per lo schema
esatto di `POST /checkout`.

## 4. Ordini & tracking

```bash theme={null}
# ordini del cliente (autenticato)
curl "$BASE/api/v1/orders" -H "Authorization: Bearer $TOKEN"
# tracking di un ordine
curl "$BASE/api/v1/orders/<id>"
```

<Check>
  Consulente rapido: la lista completa di parametri, corpi e risposte è nella
  [API Reference](/api-reference), generata dallo schema OpenAPI **live** — quindi sempre
  allineata alla produzione.
</Check>

## Aspetto & configurazione

* `GET /settings/store-info` — nome, contatti, social, **appearance** (logo, colori) per
  brandizzare il tuo frontend come il negozio.
* `GET /banners`, `GET /information/<slug>` — contenuti CMS e hero.
* `GET /languages`, `GET /currencies` — per selettori lingua/valuta.