Паспорти
Създаване, актуализиране, спиране, архивиране и масово импортиране на Цифрови продуктови паспорти. Включва блока parties за веригата от икономически оператори.
/api/v1/passportsСъздаване на паспорт
Създава един Цифров продуктов паспорт. Паспортът е обвързан с продукт (productId) и се идентифицира с GS1 GTIN + сериен номер, уникален в рамките на този GTIN. Новите паспорти започват в статус `draft` — полетата се попълват чрез следващи PATCH повиквания и паспортът се публикува от таблото, когато прегледът приключи.
/api/v1/passports/{id}Прочитане на паспорт
Прочитане на паспорт по ID. По подразбиране отговорът включва пълен паспорт — преводимите полета носят своя `sourceLocale` и карта `translations` по локал. Подайте `?lang=<locale>`, за да накарате сървъра да разреши всяко поле по веригата на публичния преглед (превод на локала на гледащия → стойност на изходния локал → английски → първи приложен → универсален източник) и да върне една резолвирана стойност за всяко поле; картата `translations` се изхвърля при отговори, разрешени по lang.
/api/v1/passportsСписък на паспортите
Пагиниран списък на паспортите в работното пространство. Филтрирайте по `productId`, `status` или free-text търсене по GTIN и сериен номер. Брои се срещу дневния бюджет за четене на паспорти (`maxV1PassportsPerDay`); елементите на отговора използват същата форма като endpoint-а за единично четене, но скъсена до полетата за списъка.
/api/v1/passports/{id}/fields/{key}Актуализиране на едно поле в паспорт
Patch на едно поле в паспорт. Стойността се валидира спрямо ключа на полето (трябва да съществува в шаблона на паспорта) и се записва с одитен запис, маркиран `via API key <prefix>`. Предпочитайте това пред записване на цялата карта `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/batchМасово създаване на паспорти
Създаване на до 100 паспорта в един повикване. Всеки елемент носи същата форма като endpoint-а за единично създаване (`{ productId, gs1: { gtin, serialNumber }, parties?, confirmOverage? }`). Частичен успех на елемент — всеки получава свой статус в масива на отговора.