TracePass
Започнете
Паспорти

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

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}

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

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

Статусът зависи от това кой записва, а не от канала. 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.

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

  • idзадължително

    ObjectId

    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