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.
Autenticazione & permessi
Serve un token staff con i permessi adeguati:
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).
La Admin API è server-side. Non incorporare mai un token staff in un client pubblico.
Esempi
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 (sezioni admin), generata dallo schema OpenAPI live. 