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

# Gestisci il negozio via API

> Catalogo, ordini, clienti e configurazione con la Admin API.

La **Admin API** (`/api/v1/admin/*`) espone la gestione completa del negozio: catalogo,
prezzi, stock, ordini, clienti, contenuti, marketing, report, impostazioni. È pensata per
backend, integrazioni (ERP/PIM/fatturazione) e automazioni — inclusi gli
[agenti AI via MCP](/ai-mcp).

## Autenticazione & permessi

Serve un **token staff** con i permessi adeguati:

```
Authorization: Bearer <staff_access_token>
```

I permessi sono granulari: `catalog`, `sales`, `customers`, `content`, `marketing`,
`reports`, `tax`, `users`, `system`. Un token vede/scrive solo nelle aree consentite dal
ruolo, e ogni chiamata è vincolata al **suo negozio** (claim `tenant_id`).

<Warning>
  La Admin API è **server-side**. Non incorporare mai un token staff in un client pubblico.
</Warning>

## Esempi

```bash theme={null}
# lista prodotti (include gli inattivi, per la gestione)
curl "$BASE/api/v1/admin/products?page=1&page_size=24" -H "Authorization: Bearer $STAFF"

# crea un prodotto
curl -X POST "$BASE/api/v1/admin/products" -H "Authorization: Bearer $STAFF" \
  -H "Content-Type: application/json" -d '{ "name":"...", "slug":"...", ... }'

# ordini + cambio stato (con transizioni validate)
curl "$BASE/api/v1/admin/orders?status=pending" -H "Authorization: Bearer $STAFF"
curl -X PATCH "$BASE/api/v1/admin/orders/<id>" -H "Authorization: Bearer $STAFF" \
  -H "Content-Type: application/json" -d '{ "status":"processing" }'
```

## Buone pratiche

* **Idempotenza & bulk**: per aggiornamenti massivi (prezzi, stock), procedi a batch e
  gestisci i 409/422 per riga.
* **Audit**: ogni mutazione admin è registrata nell'audit log del negozio.
* **Soft-delete**: eliminare un prodotto/categoria imposta `deleted_at` (non distrugge lo
  storico ordini); disattivare è cosa diversa (`is_active`).
* **Versioning**: l'API è su `/api/v1` — cambi retrocompatibili; le rotture andranno su una
  nuova versione.

Il riferimento completo dei \~200 endpoint admin è nella
[API Reference](/api-reference) (sezioni `admin`), generata dallo schema OpenAPI live.