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

# Quickstart

> La tua prima chiamata alla Storefront API in meno di un minuto.

Ti serve solo la **chiave publishable** del negozio (`cx_pk_live_<slug>_...`), fornita
dal gestore. Con quella identifichi il negozio da qualsiasi client (app mobile, script,
o un frontend che non gira sul dominio del negozio).

## 1. Leggi il catalogo

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.vellaro.io/api/v1/products?page=1&page_size=5" \
    -H "X-Vellaro-Key: cx_pk_live_demo_XXXXXXXXXXXXXXXX"
  ```

  ```javascript JavaScript theme={null}
  const res = await fetch(
    "https://api.vellaro.io/api/v1/products?page=1&page_size=5",
    { headers: { "X-Vellaro-Key": "cx_pk_live_demo_XXXXXXXXXXXXXXXX" } }
  );
  const { data, meta } = await res.json();
  console.log(data, meta); // data = prodotti, meta = paginazione
  ```

  ```python Python theme={null}
  import httpx
  r = httpx.get(
      "https://api.vellaro.io/api/v1/products",
      params={"page": 1, "page_size": 5},
      headers={"X-Vellaro-Key": "cx_pk_live_demo_XXXXXXXXXXXXXXXX"},
  )
  print(r.json()["data"])
  ```
</CodeGroup>

<Note>
  Se il tuo client gira **sul dominio del negozio** (es. `https://mionegozio.com`), le
  chiamate sono same-origin verso `https://mionegozio.com/api/v1` e la chiave non serve:
  l'infrastruttura riconosce il negozio dal dominio.
</Note>

## 2. La busta delle risposte

Ogni risposta ha lo stesso involucro:

```json theme={null}
{
  "data": [ /* payload */ ],
  "meta": { "page": 1, "page_size": 5, "total": 42, "total_pages": 9 },
  "error": null,
  "error_code": null
}
```

* `data` — il contenuto (`null` in caso di errore).
* `meta` — presente sulle liste paginate.
* `error_code` — codice macchina stabile (es. `auth.invalid_credentials`): **fai switch su
  questo** per mostrare messaggi localizzati, non su `error` (che è solo per debug).

## 3. Cosa esplorare dopo

<CardGroup cols={2}>
  <Card title="Autenticazione" icon="key" href="/authentication">
    Chiave publishable, login cliente, token staff.
  </Card>

  <Card title="Concetti" icon="book" href="/concepts">
    Negozio, envelope, errori, paginazione, i18n, immagini.
  </Card>

  <Card title="Carrello & checkout" icon="cart-shopping" href="/guides/build-storefront">
    Dal carrello all'ordine pagato.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference">
    Riferimento completo, sempre in sync con la produzione.
  </Card>
</CardGroup>