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

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

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

PATCH/api/v1/passports/{id}/parties/{role}
Изтегли OpenAPI 3.1
PATCH/api/v1/passports/{id}/parties/{role}

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

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

Поне едно от `gln`, `legacyOperatorId` или `operatorIdentifier` трябва да е зададено — без идентификатор Party не идентифицира никого. `operatorIdentifier` носи схема-тагиран структуриран идентификатор по EN 18219 §6.2–6.5 (iso6523, gln, did, doi). Когато схемата е `gln`, тя запълва и полето `gln` на ниво Party; ако и двете са зададени, трябва да съвпадат (400 с path `operatorIdentifier`). `facilityIdentifier` използва същите схеми и идентифицира местоположението на оператора — никога не запълва `gln`. Типизираните идентификатори не се задават от AI extraction или CSV import.

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

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

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

    ObjectId

    ID на паспорта.

    e.g. 6650b2c3d4e5f6a7b8c9d0e1

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

    enum

    Една от: `manufacturer`, `importer`, `authorisedRepresentative`, `distributor`, `recycler`, `producerResponsibilityOrg`. Роли извън този списък връщат 400.

    e.g. recycler

Хедъри

  • 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 за логическа операция.

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

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

    string (1-200 chars)

    Име на юридическото лице, както е вписано в търговския регистър. Задължително — Party без име не помага на никой procurement reader, независимо кой идентификатор носи.

    e.g. EuroBat Recyclers GmbH

  • gln

    string (13 digits)

    GS1 Global Location Number с валидна mod-10 контролна цифра. Силно препоръчван — когато две роли споделят един и същ `gln`, JSON-LD излъчва един party с прикачени и двете роли. Трябва да е валиден GLN; частични / само-цифрови низове връщат 400.

    e.g. 4012345678901

  • country

    string (ISO 3166-1 alpha-2)

    Двубуквен код на държавата с главни букви — напр. `DE`, `BG`, `FR`.

    e.g. DE

  • legacyOperatorId

    string (1-120 chars)

    Свободно-текстов fallback идентификатор за parties без GLN — ДДС номер, EORI, код на доставчик или произволен вътрешен ID, който вашият ERP носи. Изисква се, когато `gln` е пропуснат.

    e.g. DE123456789

  • url

    string (URL, max 500 chars)

    Страница на организацията — обикновено уебсайтът на компанията или corporate-info подстраница.

    e.g. https://eurobat-recyclers.example

  • operatorIdentifier

    object (EN 18219 §6.2–6.5)

    Структуриран идентификатор на оператора по EN 18219 §6.2–6.5. Изисква `scheme` плюс специфични за схемата полета. Схеми: `iso6523` — ICD (4-цифрен ISO/IEC 6523 код, напр. 0199 = LEI, 0088 = GLN, 0060 = DUNS) + `value`; `gln` — 13-цифрен GLN (запълва и полето `gln` на ниво Party; трябва да съвпадат ако са зададени и двете); `did` — DID URI в `did:<method>:<id>` форма (само синтактична проверка, EN 18219 §6.4.2(b)); `doi` — DOI в `10.<registrant>/<suffix>` форма (префиксът `doi:` / `https://doi.org/` се приема и премахва). Не се задава от AI extraction или CSV import.

    e.g. { "scheme": "iso6523", "icd": "0199", "value": "529900T8BM49AURSDO55" }

  • facilityIdentifier

    object (EN 18219 §6.2–6.5)

    Структуриран идентификатор на съоръжението по EN 18219 §6.2–6.5 — идентифицира къде оперира операторът, а не самия оператор. Използва същите четири схеми като `operatorIdentifier`; вариантът `gln` допълнително приема `extension` (GS1 SGLN суб-локационен код). Никога не запълва полето `gln`. Не се задава от AI extraction или CSV import.

    e.g. { "scheme": "gln", "gln": "4012345678901", "extension": "1" }

Заявка

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"
  }'

Отговор

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

Свързани endpoints