Продукти
Каталожният слой — продукти, изображения, партиди. Един продукт може да има много паспорти (по един за всяко серийно изделие).
/api/v1/productsСъздаване на продукт
Създава продукт. Шаблонът на категорията се резолвира автоматично от slug `category` — трябва да съответства на seeded категория (напр. `batteries`, `textiles`, `jewelry`). Model низовете са уникални в работното пространство.
/api/v1/products/{id}Прочитане на продукт
Прочитане на продукт по ID. Връща пълния документ, включително default стойности на полета, URL-и на изображения, template reference и текущия `passportCount`. Брои се като едно v1 четене.
/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 — изображението попада в R2 bucket-а ни и публичният URL се връща в отговора.
/api/v1/products/{id}/archiveАрхивиране на продукт
Меко архивиране. `Product.status` се сменя на `archived`; продуктът изчезва от стандартните списъци (все още видим с филтър `?showArchived=true`). Съществуващите паспорти продължават да резолвират — архивирането блокира създаването на НОВИ паспорти срещу този продукт занапред, не чупи никой QR, който вече е в ръцете на клиентите.
/api/v1/products/{id}Окончателно изтриване на продукт
**Окончателно и необратимо.** Премахва записа за продукта + всички качени документи, чиято единствена референция е този продукт (документи, свързани с други продукти/паспорти, остават, само със зачистен `productId`). R2 storage под `<companyId>/products/<productId>/` се изчиства.