Паспорти
Създаване, актуализиране, спиране, архивиране и масово импортиране на Цифрови продуктови паспорти. Включва блока 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>`). Хостът на резолвъра пренасочва `/x/*` към `/p/x/*`, така че един и същ viewer обслужва всичките пет схеми по EN 18219. Използвайте това, когато искате нашия 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}/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}Окончателно изтриване на паспорт
**Окончателно и необратимо** — записът за паспорта плюс всички каскадно свързани зависимости се премахват от базата данни. Каскадата включва AI извличания, състояние на agent сесия, заявки към доставчици, свързани само с този паспорт, събития от сканирания + сервизни събития, и всички качени документи, чиято единствена референция е този паспорт (документи, споделени с други паспорти/продукти, остават). R2 storage под папката на паспорта също се изчиства.
/api/v1/passports/batchМасово създаване на паспорти
Създаване на до 100 паспорта в едно извикване. Всеки елемент носи същата форма като endpoint-а за единично създаване (`{ productId, gs1: { gtin, serialNumber }, parties?, confirmOverage? }`). Частичен успех на елемент — всеки получава свой статус в масива на отговора.
/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История на измерванията
Връща пълната история на измерванията за паспорт на батерия, от най-нови към най-стари (по `measuredAt`). Всеки запис е обект `PassportMeasurement` с полета `_id`, `passportId`, `fieldKey`, `value`, `measuredAt`, `receivedAt`, `externalId?`, `unit?`, `materialized` (дали този запис е станал текуща стойност на полето в паспорта) и `source`. **Само за паспорти на батерии** — паспорт, различен от батерия, връща 422 `not_a_battery`.
/api/v1/passports/{id}/measurements/latestПоследни измервания
Връща най-скорошното измерване за всяко от приемливите полета за данни от употреба по Приложение XIII, точка 4. Отговорът е `{ data: { <fieldKey>: LatestMeasurement | null } }` — всички приемливи ключове са винаги налице; ключ е `null`, когато все още не е получено измерване за това поле. `LatestMeasurement` съдържа `value`, `measuredAt` и по желание `unit` и `externalId`. **Само за паспорти на батерии** — паспорт, различен от батерия, връща 422 `not_a_battery`.