Продукти
Каталожният слой — продукти, изображения, партиди. Един продукт може да има много паспорти (по един за всяко серийно изделие).
/api/v1/productsСъздаване на продукт
Създава продукт. Шаблонът на категорията се резолвира автоматично от slug `category` — трябва да съответства на seeded категория (напр. `battery`, `textile`, `jewelry`). Model низовете са уникални в работното пространство.
/api/v1/products/{id}Прочитане на продукт
Прочитане на продукт по ID. Връща пълния документ, включително default стойности на полета, URL-и на изображения, template reference и текущия `passportCount`. Този endpoint не консумира дневен брояч за четения.
/api/v1/productsСписък на продуктите
Пагиниран списък на всички продукти в работното пространство, сортирани по `createdAt` низходящо. Размер на страница макс. 100. Филтрирайте по slug на категория, status (`active` / `archived`) или free-text търсене по name + model.
/api/v1/products/{id}Актуализиране на продукт
Patch на едно или повече полета на продукт. Изпратете само ключовете, които искате да промените — пропуснатите полета остават непроменени. Семантиката на цял масив за `imageUrls` е умишлена: CMS на клиента е каноничният източник на изображения, така че PATCH с `imageUrls: ["a","b"]` заменя предишните. За добавяне на едно изображение без презаписване, използвайте multipart upload endpoint.
/api/v1/products/{id}/imagesКачване на изображение на продукт
Качване на единичен файл с изображение (multipart/form-data, име на полето `file`) и добавянето му към масива `imageUrls` на продукта. Използвайте това, когато нямате готов CDN URL — TracePass съхранява изображението и връща публичния му URL в отговора.
/api/v1/products/{id}/archiveАрхивиране на продукт
Меко архивиране. `Product.status` се сменя на `archived`; промяната е еднопосочна (няма endpoint за разархивиране). Архивираните продукти продължават да се показват в `GET /api/v1/products`; подайте `status=active`, за да ги изключите. Разрешено е само след като всички паспорти на продукта са архивирани (иначе 409) — и архивирането на продукт не предотвратява създаването на нови паспорти срещу него.
/api/v1/products/{id}Окончателно изтриване на продукт
**Окончателно и необратимо.** Премахва записа за продукта + всички качени документи, чиято единствена референция е този продукт (документи, свързани с други продукти/паспорти, остават, само със зачистен `productId`). Съхранените файлове, принадлежащи само на този продукт, също се изтриват.