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.

LEI (iso6523 с ICD 0199) се проверява в регистъра на GLEIF. Ако GLEIF не го познава или го отчита като ANNULLED или DUPLICATE, отговорът е 400 (при дубликат съобщението посочва LEI, който да се използва). LEI със статус LAPSED, RETIRED или на неактивно лице, както и legalName, който не съвпада с нито едно от имената му в GLEIF, се записва и се отчита в масив warnings в отговора.

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

След като паспорт на батерия е пуснат на пазара, запис, който би променил съхранен operatorIdentifier или facilityIdentifier, връща 409 operator_locked (keys посочва <role>.<field>); другите промени по страните остават разрешени. За корекция на заключен идентификатор маркирайте паспорта за изтриване и създайте нов.

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

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

    string (24 hex chars)

    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

  • tradeName

    string (max 200 chars)

    Регистрирано търговско наименование или регистрирана търговска марка. За вносител на батерии това е един от данните, които той посочва върху батерията (Регламент за батериите, чл. 41, параграф 3); проверката за съответствие предупреждава, когато го няма за вносителя, който пуска батерията на пазара. Показва се в публичния паспорт.

    e.g. EuroBat

  • postalAddress

    string (max 500 chars)

    Пощенски адрес с едно звено за контакт, на един ред. Показва се в публичния паспорт.

    e.g. Industriestraße 42, 80339 Munich, Germany

  • email

    string (email)

    Адрес на електронна поща за контакт. Показва се в публичния паспорт, затова използвайте фирмен адрес за контакт, а не личен.

    e.g. compliance@example.com

  • 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