Prodotti
Il livello del catalogo — prodotti, immagini, lotti. Un prodotto può avere molti passaporti (uno per unità serializzata).
/api/v1/productsCreare un prodotto
Crea un prodotto. Il template di categoria viene risolto automaticamente dallo slug `category` — deve corrispondere a una categoria preconfigurata (es. `batteries`, `textiles`, `jewelry`). Le stringhe model sono univoche all'interno dello spazio di lavoro.
/api/v1/products/{id}Leggere un singolo prodotto
Legge un prodotto per ID. Restituisce il documento completo, inclusi i valori predefiniti dei campi, gli URL delle immagini, il riferimento al template e il `passportCount` corrente. Conta come una lettura v1.
/api/v1/productsElencare i prodotti
Elenco paginato di ogni prodotto posseduto dallo spazio di lavoro, ordinato per `createdAt` decrescente. Dimensione della pagina limitata a 100. Filtrate per slug di categoria, status (`active` / `archived`), oppure con una ricerca a testo libero su nome + model.
/api/v1/products/{id}Aggiornare un prodotto
Applica una patch a uno o più campi del prodotto. Inviate solo le chiavi che volete modificare — i campi omessi restano invariati. La semantica dell'intero array su `imageUrls` è intenzionale: il vostro CMS è l'insieme canonico delle immagini, quindi un PATCH con `imageUrls: ["a","b"]` sostituisce ciò che era presente. Per aggiungere una singola immagine senza riscrivere l'elenco, usate invece l'endpoint di caricamento multipart.
/api/v1/products/{id}/imagesCaricare un'immagine del prodotto
Carica un singolo file immagine (multipart/form-data, nome del campo `file`) e lo aggiunge in coda all'array `imageUrls` del prodotto. Usatelo quando non avete pronto un URL del CDN — l'immagine finisce nel nostro bucket R2 e l'URL pubblico viene restituito nella risposta.
/api/v1/products/{id}/archiveArchiviare un prodotto
Archiviazione leggera. `Product.status` passa a `archived`; il prodotto scompare dagli elenchi predefiniti (ancora visibile con il filtro `?showArchived=true`). I passaporti esistenti continuano a risolvere — l'archiviazione blocca la creazione di NUOVI passaporti contro questo prodotto d'ora in poi, non rompe alcun QR già nelle mani dei clienti.
/api/v1/products/{id}Eliminare un prodotto definitivamente
**Permanente e irreversibile.** Rimuove la riga del prodotto + qualsiasi documento caricato la cui unica referenza era questo prodotto (i documenti collegati ad altri prodotti/passaporti restano, solo con `productId` rimosso). Lo storage R2 sotto `<companyId>/products/<productId>/` viene ripulito.