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. `battery`, `textile`, `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. Questo endpoint non consuma alcun contatore di lettura giornaliero.
/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 — TracePass archivia l'immagine e restituisce il suo URL pubblico nella risposta.
/api/v1/products/{id}/archiveArchiviare un prodotto
Archiviazione leggera. `Product.status` passa a `archived`; la modifica è definitiva (nessun endpoint la annulla). I prodotti archiviati restano in `GET /api/v1/products`; passa `status=active` per escluderli. Consentito solo quando tutti i passaporti del prodotto sono archiviati (altrimenti 409) — e archiviare un prodotto non impedisce la creazione di nuovi passaporti per esso.
/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). Vengono eliminati anche i file archiviati che appartenevano solo a questo prodotto.