---
title: Upsert на икономически оператор (party)
description: Задаване или замяна на един икономически оператор в паспорт (производител, вносител, дистрибутор, упълномощен представител). Валидиран GLN. Одитна следа.
canonical: "https://www.tracepass.eu/bg/docs/upsert-party"
locale: bg
source: "https://www.tracepass.eu/bg/docs/upsert-party"
---

# Upsert на икономически оператор (party)

> Задаване или замяна на един икономически оператор в паспорт (производител, вносител, дистрибутор, упълномощен представител). Валидиран GLN. Одитна следа.

```http
PATCH /api/v1/passports/{id}/parties/{role}
```

Създава или заменя Party за една роля в паспорт. Path сегментът role определя слота, в който пишете — `manufacturer`, `importer`, `authorisedRepresentative`, `distributor`, `recycler`, `producerResponsibilityOrg`. Изпращането на същата роля два пъти е upsert: съществуващият блок се заменя атомично.

Идентичността се изразява изцяло чрез тялото: `legalName` (задължително), `gln` (GS1 Global Location Number — силно препоръчван за разграничаване на много роли), `country` (ISO 3166-1 alpha-2), `legacyOperatorId` (VAT / EORI / код на доставчик като свободно-текстов fallback), `url`. Поне едно от `gln` или `legacyOperatorId` трябва да е зададено — без идентификатор Party не идентифицира никого. Когато две роли споделят един и същ `gln`, JSON-LD emission ги колапсва в един party с множество роли.

Брои се като едно v1 записване. Поддържа Idempotency-Key. Регламентът за батериите изисква поне { manufacturer, importer (ако е приложимо), recycler } преди паспортът да бъде приет; scorecard за регулаторно покритие показва липсващите роли в таблото. Съответстващият `DELETE /api/v1/passports/{id}/parties/{role}` премахва роля идемпотентно.

## 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 на паспорта. |
| `role` | path | enum | yes | Една от: `manufacturer`, `importer`, `authorisedRepresentative`, `distributor`, `recycler`, `producerResponsibilityOrg`. Роли извън този списък връщат 400. |
| `legalName` | body | string (1-200 chars) | yes | Име на юридическото лице, както е вписано в търговския регистър. Задължително — Party без име не помага на никой procurement reader, независимо кой идентификатор носи. |
| `gln` | body | string (13 digits) | no | GS1 Global Location Number с валидна mod-10 контролна цифра. Силно препоръчван — когато две роли споделят един и същ `gln`, JSON-LD излъчва един party с прикачени и двете роли. Трябва да е валиден GLN; частични / само-цифрови низове връщат 400. |
| `country` | body | string (ISO 3166-1 alpha-2) | no | Двубуквен код на държавата с главни букви — напр. `DE`, `BG`, `FR`. |
| `legacyOperatorId` | body | string (1-120 chars) | no | Свободно-текстов fallback идентификатор за parties без GLN — ДДС номер, EORI, код на доставчик или произволен вътрешен ID, който вашият ERP носи. Изисква се, когато `gln` е пропуснат. |
| `url` | body | string (URL, max 500 chars) | no | Страница на организацията — обикновено уебсайтът на компанията или corporate-info подстраница. |

## Examples

```bash
curl -sS -X PATCH \
  https://app.tracepass.eu/api/v1/passports/6650b2c3d4e5f6a7b8c9d0e1/parties/recycler \
  -H "Authorization: Bearer tp_REDACTED_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "legalName": "EuroBat Recyclers GmbH",
    "gln": "4012345678901",
    "country": "DE",
    "url": "https://eurobat-recyclers.example"
  }'
```

```typescript
await fetch(
  `https://app.tracepass.eu/api/v1/passports/${id}/parties/recycler`,
  {
    method: "PATCH",
    headers: {
      Authorization: `Bearer ${process.env.TRACEPASS_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      legalName: "EuroBat Recyclers GmbH",
      gln: "4012345678901",
      country: "DE",
      url: "https://eurobat-recyclers.example",
    }),
  },
);
```

```python
import os, requests
res = requests.patch(
    f"https://app.tracepass.eu/api/v1/passports/{passport_id}/parties/recycler",
    headers={"Authorization": f"Bearer {os.environ['TRACEPASS_API_KEY']}"},
    json={
        "legalName": "EuroBat Recyclers GmbH",
        "gln": "4012345678901",
        "country": "DE",
        "url": "https://eurobat-recyclers.example",
    },
)
res.raise_for_status()
```

## Responses

### 200 — Upsert-нат

```json
{
  "role": "recycler",
  "party": {
    "legalName": "EuroBat Recyclers GmbH",
    "gln": "4012345678901",
    "country": "DE",
    "url": "https://eurobat-recyclers.example",
    "status": "active"
  },
  "version": 5
}
```

### 400 — Валидационна грешка

```json
{
  "error": "Validation error",
  "details": {
    "fieldErrors": {
      "gln": ["Party must have at least one identifier (gln or legacyOperatorId)"]
    }
  }
}
```

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

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

## Related

- [Създаване на паспорт (parties при създаване)](https://www.tracepass.eu/bg/docs/create-passport.md)
- [Актуализиране на едно поле](https://www.tracepass.eu/bg/docs/update-field.md)