---
title: Актуализиране на едно поле в паспорт
description: Актуализиране на едно поле в паспорт с одитен запис. По подразбиране status approved; override до ai_suggested или supplier за маршрут към review queue.
canonical: "https://www.tracepass.eu/bg/docs/update-field"
locale: bg
source: "https://www.tracepass.eu/bg/docs/update-field"
---

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

> Актуализиране на едно поле в паспорт с одитен запис. По подразбиране status approved; override до ai_suggested или supplier за маршрут към review queue.

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

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

Записванията по подразбиране са `status: "approved"` — интеграциите, задвижвани от API ключ, са доверени по конвенция (за разлика от редакторите в таблото, където не-администратори записват `pending_review`). Заменете с `source: "ai_suggested"` или `source: "supplier"`, ако искате стойността да попадне в опашката за преглед.

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

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Authorization` | header | string | yes | `Bearer <token>` — или `tp_` API ключ (Developer → API Keys; най-просто, за server-to-server), или OAuth 2.0 access token (Developer → OAuth Apps; за приложения, авторизирани от потребител, scoped и отзоваеми). Страницата Authentication съдържа пълния OAuth поток и списъка със scopes. |
| `Idempotency-Key` | header | string | no | UUID v4 за логическа операция. |
| `id` | path | ObjectId | yes | ID на паспорта. За адресиране по сериен номер вместо това използвайте PATCH /api/v1/passports/by-serial/{serial}/fields/{key}. |
| `key` | path | string | yes | Ключ на полето (camelCase), както е дефиниран в шаблона на паспорта — напр. `nominalVoltage`, `batteryChemistry`, `recycledContentCobalt`. 400, ако ключът не е в шаблона. |
| `value` | body | string \| number \| boolean \| array \| object | yes | Нова стойност. Платформата не преформатира низове в числа — изпратете стойността в типа, който очаква полето на шаблона. |
| `source` | body | enum | no | Маркер за произхода на стойността. Една от: `manual`, `ai_suggested`, `ai_approved`, `reference_db`, `supplier`, `system`. По подразбиране `manual`. `ai_suggested` и `supplier` отиват в опашката за преглед; всички останали пишат като approved. |
| `sourceLocale` | body | string (ISO 639-1) | no | Локал на стойността (един от 24-те EU локала). Управлява посоката на превода + езиковото разрешаване на публичния преглед. По подразбиране `sourceLocale` на паспорта, когато е пропуснат. |

## Examples

```bash
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 }'
```

```typescript
await fetch(
  `https://app.tracepass.eu/api/v1/passports/${id}/fields/ratedCapacity`,
  {
    method: "PATCH",
    headers: {
      Authorization: `Bearer ${process.env.TRACEPASS_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ value: 5.24 }),
  },
);
```

```python
import os, requests
res = requests.patch(
    f"https://app.tracepass.eu/api/v1/passports/{passport_id}/fields/ratedCapacity",
    headers={"Authorization": f"Bearer {os.environ['TRACEPASS_API_KEY']}"},
    json={"value": 5.24},
)
res.raise_for_status()
```

## Responses

### 200 — Актуализиран

```json
{
  "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
}
```

### 400 — Невалиден ключ

```json
{ "error": "Invalid field key: notARealField" }
```

### 404 — Не е намерен

```json
{ "error": "Passport not found" }
```

## Related

- [Създаване на паспорт](https://www.tracepass.eu/bg/docs/create-passport.md)
- [Прикачване на икономически оператор](https://www.tracepass.eu/bg/docs/upsert-party.md)