Паспорти

Актуализиране на едно поле в паспорт

Patch на едно поле в паспорт. Стойността се валидира спрямо ключа на полето (трябва да съществува в шаблона на паспорта) и се записва с одитен запис, който посочва идентификационните данни (via API key <prefix> или via OAuth app <client>) и, когато е зададен хедърът X-Source, извикващия клиент, напр. (mcp). Предпочитайте това пред записване на цялата карта fields, когато трябва да актуализирате само едно число — това е по-малко записване, а одитният запис на полето е това, което виждат прегледашите в таблото.

PATCH/api/v1/passports/{id}/fields/{key}

Изтегли OpenAPI 3.1

PATCH/api/v1/passports/{id}/fields/{key}

Актуализиране на едно поле в паспорт

Статусът зависи от това кой записва, а не от канала. API ключът записва status: "approved" (той е служебен акаунт на ниво компания). OAuth токенът записва с правата на своя потребител в таблото, така че роля под admin записва pending_review. Стойност, изпратена със source: "ai_suggested", винаги попада в pending_review и заявката се отхвърля (статус 400), когато стойността може да бъде декларирана само от икономическия оператор или трябва да бъде измерена (напр. stateOfHealth на батерия); изпратете я с друг източник, ако вашата организация прави това изявление. ai_approved и system се задават от TracePass и се отхвърлят като стойности в заявката.

Алтернативна форма за адресиране съществува на PATCH /api/v1/passports/by-serial/{serial}/fields/{key} — същото тяло, същият отговор, полезна е когато вашият ERP знае само серийния номер от страна на клиента. Брои се като едно v1 записване. Поддържа Idempotency-Key.

No-op (200 unchanged: true): когато входящата стойност, изчисленият статус и езикът на произход са идентични на съхраненото състояние, endpoint-ът пропуска записа изцяло — без увеличение на версията, без одитен запис, без snapshot — и връща 200 с unchanged: true заедно с текущото поле и версия. Тялото на отговора е в същия формат като при реален запис; проверете ключа unchanged, за да разграничите двата случая.

Защита на задължително поле (400): след публикуване на паспорт, изпращането на null или празен низ за поле, което регламентът изисква за категорията на паспорта, се отхвърля с required_field_empty (HTTP 400). Масивът fields в тялото на отговора посочва всеки засегнат ключ. Черновите остават свободни за редакция.

Ограничения на размера (400 / 413): стойността може да съдържа най-много 1000 елемента в масиви (включително вложените), 20 000 знака във всеки отделен низ (всеки език на преводима стойност се брои отделно) и общо 256 KB, с влагане до 8 нива. По-голяма стойност се отхвърля с field_value_too_large, като се посочват полето, видът на ограничението (items, characters, bytes или depth) и стойността му. Тяло на заявката, обявено като по-голямо от 1 MB, се отхвърля с 413 payload_too_large.

Заключване при запис (409): след като паспортът е публикуван, идентификационните полета (gtin, serialNumber, uniqueProductIdentifier, globalUniqueProductIdentifier, productIdentifier, identifierStandard, batteryUniqueIdentifier, batteryIdDmcCode, batteryPassportIdentifier) не могат да се променят, ако вече съдържат одобрена (approved) стойност — отговорът е 409 identifier_locked с имената на полетата в keys. Стойност в статус pending_review може да бъде коригирана; празно поле може да бъде попълнено. Записването на същата стойност (включително GTIN с или без начална нула до 14 цифри, или съответствие след премахване на интервалите) се приема, когато записът запазва стойността одобрена, както прави API ключът. Запис със source: "ai_suggested" или от OAuth потребител под ниво admin постъпва като pending_review и се отказва. Запис в архивиран паспорт връща 409 passport_archived. Паралелна надпревара за запис връща 409 concurrent_update — заредете отново и опитайте пак. Спряните и изтеклите паспорти остават редактируеми.

Параметри в пътя

idзадължително
string (24 hex chars)
ID на паспорта. За адресиране по сериен номер вместо това използвайте PATCH /api/v1/passports/by-serial/{serial}/fields/{key}.
e.g. 6650b2c3d4e5f6a7b8c9d0e1
keyзадължително
string
Ключ на полето (camelCase), както е дефиниран в шаблона на паспорта — напр. nominalVoltage, batteryChemistry, recycledContentCobalt. 400, ако ключът не е в шаблона.
e.g. ratedCapacity

Хедъри

Authorizationзадължително
string
Bearer <token> — или tp_ API ключ (Developer → API Keys; най-просто, за server-to-server), или OAuth 2.0 access token (Developer → OAuth Apps; за приложения, авторизирани от потребител, scoped и отзоваеми). Страницата Authentication съдържа пълния OAuth поток и списъка със scopes.
e.g. Bearer tp_REDACTED_xxxxxxxxxxxx
Idempotency-Key
string
UUID v4 за логическа операция.

Полета в тялото

valueзадължително
string | number | boolean | array | object
Нова стойност. Платформата не преформатира низове в числа — изпратете стойността в типа, който очаква полето на шаблона.
e.g. 5.24
source
enum
Маркер за произхода на стойността. Една от: manual, ai_suggested, reference_db, supplier. По подразбиране manual. ai_suggested отива в опашката за преглед; останалите се записват с правата на вашите идентификационни данни. ai_approved и system се задават от TracePass и тук се отхвърлят.
sourceLocale
string (ISO 639-1)
Локал на стойността (един от 24-те EU локала). Управлява посоката на превода + езиковото разрешаване на публичния преглед. По подразбиране sourceLocale на паспорта, когато е пропуснат.

Заявка

curl -sS -X PATCH \
  https://app.tracepass.eu/api/v1/passports/6650b2c3d4e5f6a7b8c9d0e1/fields/ratedCapacity \
  -H "Authorization: Bearer tp_REDACTED_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "value": 5.24 }'

Отговор

{
  "field": {
    "value": 5.24,
    "source": "manual",
    "status": "approved",
    "accessLevel": "public",
    "sourceLocale": "en",
    "lastUpdatedAt": "2026-05-09T10:30:00.000Z",
    "lastUpdatedBy": "api_key:tp_89b2482d"
  },
  "version": 4
}

Актуализиране на едно поле в паспорт

Параметри в пътя

Хедъри

Полета в тялото

Заявка

Отговор

Свързани endpoints