Паспорти
Създаване, актуализиране, спиране, архивиране и масово импортиране на Цифрови продуктови паспорти. Включва блока parties за веригата от икономически оператори.
/api/v1/passportsСъздаване на паспорт
Създава един Цифров продуктов паспорт. Паспортът е обвързан с продукт (productId) и се идентифицира с GS1 GTIN + сериен номер, уникален в рамките на този GTIN. Новите паспорти започват в статус `draft` — полетата се попълват чрез следващи PATCH повиквания и паспортът се публикува от таблото, когато прегледът приключи.
/api/v1/passports/{id}Прочитане на паспорт
Прочитане на паспорт по ID. По подразбиране отговорът включва пълен паспорт — преводимите полета носят своя `sourceLocale` и карта `translations` по локал. Подайте `?lang=<locale>`, за да накарате сървъра да разреши всяко поле по веригата на публичния преглед (превод на локала на гледащия → стойност на изходния локал → английски → първи приложен → универсален източник) и да върне една резолвирана стойност за всяко поле; картата `translations` се изхвърля при отговори, разрешени по lang.
/api/v1/passports/{id}/qrРендиране на QR на паспорт
Връща прясно рендиран QR код за паспорта, кодиращ неговия ефективен идентификаторен URI. За GS1 паспорти това е GS1 Digital Link URI (`/01/<gtin>/21/<serial>`); за ISO 15459 — пътят на resolver-а; за iec61406, did и doi паспорти — пътят на resolver-а `/x/<scheme>/<encodedValue>` (напр. `https://id.tracepass.eu/x/did/<encodedDid>`). И петте схеми по EN 18219 се разрешават до един и същ публичен viewer. Използвайте това, когато искате нашия renderer (консистентна quiet zone, корекция на грешки, по избор брандиране) вместо сами да кодирате URI. По подразбиране връща `image/svg+xml`; `?format=png` връща PNG, а `?format=json` връща обвивка `{ result: "<svg>" }` за вграждане.
/api/v1/passports/{id}/complianceПроверка на съответствието на паспорт
Връща тристепенна оценка за съответствие за един паспорт — `compliant`, `compliant_with_warnings` или `incomplete` — заедно с findings, цитиращи регламента, така че интеграция може да направи анализ на пропуските на паспорт, да поправи цитираните пропуски и да извика отново за потвърждение. Тази верига четене → поправка → проверка е целта: отговорът казва на AI агента точно какво да зададе след това.
/api/v1/passports/{id}/registry-readinessПроверка на готовността за регистъра
Връща дали паспорт би преминал **формалната проверка за подаване на EU DPP Registry** — `{ ready, findings[] }`. Това е *механичната* проверка на регистъра преди подаване, различна от и допълваща същинската оценка `/compliance`: паспорт може да е готов за регистъра, но да не е същински съответстващ, и обратно. Извикайте я преди подаване към регистъра, за да откриете формалните пропуски рано.
/api/v1/passportsСписък на паспортите
Пагиниран списък на паспортите в работното пространство. Филтрирайте по `productId`, `status` или free-text търсене по GTIN и сериен номер. Брои се срещу дневния бюджет за четене на паспорти (`maxV1PassportsPerDay`); елементите на отговора използват същата форма като endpoint-а за единично четене, но скъсена до полетата за списъка.
/api/v1/passports/{id}/fields/{key}Актуализиране на едно поле в паспорт
Patch на едно поле в паспорт. Стойността се валидира спрямо ключа на полето (трябва да съществува в шаблона на паспорта) и се записва с одитен запис, който посочва идентификационните данни (`via API key <prefix>` или `via OAuth app <client>`) и, когато е зададен хедърът `X-Source`, извикващия клиент, напр. `(mcp)`. Предпочитайте това пред записване на цялата карта `fields`, когато трябва да актуализирате само едно число — това е по-малко записване, а одитният запис на полето е това, което виждат прегледашите в таблото.
/api/v1/passports/{id}/parties/{role}Upsert на икономически оператор (party)
Създава или заменя Party за една роля в паспорт. Path сегментът role определя слота, в който пишете — `manufacturer`, `importer`, `authorisedRepresentative`, `distributor`, `recycler`, `producerResponsibilityOrg`. Изпращането на същата роля два пъти е upsert: съществуващият блок се заменя атомично.
/api/v1/passports/{id}/registry-upiАдрес за EU DPP Registry на паспорт на батерия
Връща уникалния идентификатор на продукта (UPI), който се поставя в онлайн формуляра на EU DPP Registry за един публикуван паспорт на **батерия**, като `{ upi, preparedAt }`. Икономическият оператор регистрира паспорта на уебсайта на регистъра със собствения си EU Login (Product group: Batteries; Granularity: Item). TracePass подготвя адреса и записва, че го е подготвил; никога не подава нищо към регистъра.
/api/v1/registry/upload-fileФайл за качване в EU DPP Registry за паспорти на батерии
Създава XML файла, който икономическият оператор качва на уебсайта на EU DPP Registry (DPP Registration → upload a file), за посочените от вас паспорти на **батерии**, до 100 на извикване. Регистрацията е собствено действие на оператора със собствения му EU Login; TracePass подготвя файла и никога не го подава.
/api/v1/passports/{id}/registrationЗаписване на резултата от EU DPP Registry за паспорт на батерия
Записва това, което икономическият оператор съобщава от уебсайта на EU DPP Registry, за един публикуван паспорт на **батерия**. TracePass записва изявлението на оператора и не го проверява в регистъра. Тялото има една от две форми според `environment`.
/api/v1/passports/{id}/registrationОтмяна на погрешен запис за EU DPP Registry
Изчиства резултат, записан с `POST /api/v1/passports/{id}/registration`; задължителният параметър на заявката `environment` посочва кой. Това не променя нищо в самия EU DPP Registry: коригира това, което TracePass пази за паспорта. Отмяната се записва.
/api/v1/passports/{id}/place-on-marketИзпращане на паспорт на батерия към API на регистър по EN 18222
Изпраща публикуван паспорт на **батерия** към регистър, който приема извикването `registerDPP` по EN 18222, чрез достъпа до API на регистъра, настроен за вашия акаунт (API ключ или bearer token), така че записът се прави с вашите собствени идентификационни данни. Само паспорти на батерии.
/api/v1/passports/{id}/suspendСпиране на паспорт
Реверсибилно спиране. Публичният преглед се превключва на страницата за suspended състояние (HTTP 423 със структурирано тяло); QR сканиранията ефективно умират, без URL-ът да става 404. Използвайте за изтегляния, спорове, вътрешни holds или разследвания за качество. Republish от таблото след разрешаване.
/api/v1/passports/{id}/archiveАрхивиране на паспорт (необратимо)
**Необратимо.** Публичният преглед връща 404, GS1 Digital Link URL спира да резолвира, QR кодът умира завинаги, освен ако паспортът не е пренасочен към нов доставчик. Използвайте САМО за продукти, които никога не са били изпратени — архивирането на паспорт за продукт, вече в ръцете на клиенти, чупи всяко QR сканиране, което някога ще направят.
/api/v1/passports/{id}/mark-for-deletionМаркиране на паспорт за изтриване
**Първа от две стъпки.** Изтриването на паспорт става на две стъпки: първо го маркирате за изтриване тук, след това извиквате `DELETE /api/v1/passports/{id}` (непубликуван паспорт в статус `draft` или `in_review` може да се изтрие директно). Изтриването е меко (soft delete): нищо не се заличава, но паспортът изчезва от API и от всичко, което е публично достъпно. Сканирането на QR кода показва страница, че паспортът е прекратен, а машинночетимите формати връщат `410 Gone`.
/api/v1/passports/{id}Изтриване на паспорт
**Паспорт, маркиран за изтриване → меко изтриване.** Изтриването на паспорт, който е бил публикуван, става на две стъпки: първо `POST /api/v1/passports/{id}/mark-for-deletion`, след това този DELETE. Нищо не се заличава: паспортът изчезва от API (оттук нататък всяко v1 извикване за него връща `404`) и от всичко, което е публично достъпно. Сканирането на QR кода показва страница, че паспортът е прекратен, а машинночетимите формати връщат `410 Gone`. Връща паспорта със `status: "deleted"` и изпраща webhook `passport.deleted`.
/api/v1/passports/batchМасово създаване на паспорти
Създаване на до 100 паспорта в едно извикване. Всеки елемент носи същата форма като endpoint-а за единично създаване (`{ productId, gs1: { gtin, serialNumber }, parties? }`). Частичен успех на елемент — всеки получава свой статус в масива на отговора.
/api/v1/passports/{id}/snapshotsСписък на моментните снимки на паспорт
Връща страничен списък с моментни снимки на паспорт, от най-нов към най-стар. Снимка се записва при публикуване и след всяка промяна на публикуван, спрян, изтекъл или архивиран паспорт — стойности на полета, преводи, страни, смяна на статус, отговори на доставчици, записи от ИИ, възстановявания — когато съдържанието на паспорта действително се е променило (EN 18221:2026, т. 4.2). Всеки запис включва id на снимката, номер на версията, причина (напр. `published`, `field_edit`, `status_change`, `baseline`), кой е направил промяната (`actor`, когато е известно), времеви печат, хеш на съдържанието и дали хешът все още потвърждава — `hashValid: false` показва подправяне на данните.
/api/v1/passports/{id}/snapshots/{snapshotId}Вземане на моментна снимка на паспорт
Връща пълния архивен запис на една моментна снимка: пълният JSON-LD payload точно такъв, какъвто е бил паспортът при създаването на снимката — при публикуване или след всяка промяна на публикуван, спрян, изтекъл или архивиран паспорт — метаданните на снимката (версия, причина, `actor` — кой е направил промяната — и времеви печат) и повторна проверка на хеша на съдържанието. За да получите версията, валидна към дадена дата, използвайте `?at=` в **Списък на моментните снимки на паспорт**. `hashValid: false` означава, че съхраненият payload е бил модифициран след като снимката е направена — признак за подправяне на данните.
/api/v1/passports/{id}/condition-flagsПрочитане на флагове за условна класификация
Връща разрешения **condition profile** за паспорт — `Record<flagKey, { value, status, source }>`. Condition flags са одобрени от рецензент факти да/не за продукт, които активират условни правни задължения. За паспорти на батерии по Регламент (ЕС) 2023/1542 регистрираните флагове са: `hasBMS` (наличие на система за управление на батерии), `rechargeable` (батерията е презареждаема), `externalStorageOnly` (прилага се изключение по чл. 8), и `isStationaryBess` (стационарна батерийна система за съхранение на енергия). Категории без регистрирани флагове връщат празен профил.
/api/v1/passports/{id}/condition-flagsЗадаване на флагове за условна класификация
Записва един или повече condition flags към паспорт. Тялото на заявката е `Record<flagKey, boolean | null>` — `true` или `false` задава флага; `null` го изчиства. Само ключове, регистрирани за категорията на паспорта, се приемат; непознати ключове връщат 400 с допустимите ключове за тази категория.
/api/v1/passports/{id}/measurementsЗаписване на измервания
**Само за паспорти на батерии** (Регламент (ЕС) 2023/1542, чл. 77, Приложение XIII, точка 4 — данни от употреба). Паспортът трябва да е публикуван; чернова или спрян паспорт връща 422 `passport_not_active`. Паспорт, който не е за батерия, връща 422 `not_a_battery`. Изпращайте 1–500 измервания на извикване, всяко като `{ fieldKey, value, measuredAt, externalId?, unit? }` — `measuredAt` е времеви печат по ISO 8601 и не трябва да е в бъдещето; `value` трябва да е най-много **16 KB след сериализация** (по-голяма стойност връща 400 `invalid_value`). Приемливите `fieldKey` са полетата за данни от употреба по Приложение XIII, точка 4: `stateOfHealth`, `stateOfCertifiedEnergy`, `remainingCapacity`, `remainingPowerCapability`, `remainingRoundTripEfficiency`, `evolutionOfSelfDischargeRate`, `currentInternalResistancePack`, `capacityFade`, `powerFade`, `internalResistanceIncrease`, `dynamicRatedCapacity`, `dynamicPowerCapability`, `dynamicInternalResistance`, `dynamicEnergyRoundTripEfficiency`, `dynamicExpectedLifetimeCycles`, `numberOfFullEquivalentChargingCycles`, `numberOfChargingEvents`, `currentStateOfCharge`, `negativeEvents`, `temperatureConditionsHistorical`.
/api/v1/passports/{id}/measurementsИстория на измерванията
Връща пълната история на измерванията за паспорт, от последно получените към най-старите (по `receivedAt`). Всеки запис е обект `PassportMeasurement` с полета `_id`, `passportId`, `fieldKey`, `value`, `measuredAt`, `receivedAt`, `externalId?`, `unit?`, `materialized` (дали този запис е станал текуща стойност на полето в паспорта) и `source`.
/api/v1/passports/{id}/measurements/latestПоследни измервания
Връща най-скорошното измерване за всяко от приемливите полета за данни от употреба по Приложение XIII, точка 4. Отговорът е `{ data: { <fieldKey>: LatestMeasurement | null } }` — всички приемливи ключове са винаги налице; ключ е `null`, когато все още не е получено измерване за това поле. `LatestMeasurement` съдържа `value`, `measuredAt` и по желание `unit` и `externalId`.