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: съществуващият блок се заменя атомично.

Идентичността се изразява изцяло чрез тялото: `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}` премахва роля идемпотентно.

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

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

    ObjectId

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

    e.g. 6650b2c3d4e5f6a7b8c9d0e1

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

    enum

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

    e.g. recycler

Хедъри

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

    string

    `Bearer <api-key>`.

    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

Заявка

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