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}/linksOttenere il pacchetto di link per rivenditori
Restituisce il pacchetto di link per rivenditori di un prodotto: ogni passaporto pubblicato con seriale, URL del passaporto e stato, più l'URL della pagina del modello del prodotto. È la risposta in una sola chiamata a una richiesta di un rivenditore ai sensi dell'articolo 10, paragrafo 3, lettera b) dell'ESPR, che chiede un link a una pagina web o una copia del supporto dati entro cinque giorni lavorativi dalla richiesta.
/api/v1/products/{id}/links/model-qrRenderizzare il QR della pagina del modello
Renderizza il codice QR della pagina del modello del prodotto, l'indirizzo GS1 semplice `/01/{gtin}` elencato in `GET /api/v1/products/{id}/links`. La pagina del modello mostra solo i valori pubblici identici in ogni unità pubblicata, quindi il codice è adatto a un annuncio online o a un rivenditore; ogni unità mantiene il proprio passaporto. Nero su sfondo trasparente. Conta come una lettura v1.
/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.