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

Създаване на паспорт

Създава един Цифров продуктов паспорт. Паспортът е обвързан с продукт (productId) и се идентифицира с GS1 GTIN + сериен номер, уникален в рамките на този GTIN. Новите паспорти започват в статус draft — полетата се попълват чрез следващи PATCH повиквания и паспортът се публикува от таблото, когато прегледът приключи.

POST/api/v1/passports
Изтегли OpenAPI 3.1
POST/api/v1/passports

Създаване на паспорт

Създава един Цифров продуктов паспорт. Паспортът е обвързан с продукт (productId) и се идентифицира с GS1 GTIN + сериен номер, уникален в рамките на този GTIN. Новите паспорти започват в статус draft — полетата се попълват чрез следващи PATCH повиквания и паспортът се публикува от таблото, когато прегледът приключи.

GTIN трябва да е 14 цифри (или 13-цифрен EAN, допълнен до 14) с валидна GS1 контролна цифра и да не е регистриран от друг тенант. Брои се като едно v1 записване. Паспортът се създава като чернова, а черновата не заема място от лимита maxDpps на плана. Затова създаването никога не връща грешка за overage и не се таксува. Лимитът на плана и евентуалната такса за паспорт над него се прилагат, когато паспортът се публикува от таблото.

Поддържа незадължителен Idempotency-Key заголовък — платформата повтаря оригиналния 201 отговор в продължение на 24 часа за същия ключ, така че повторни мрежови опити са безопасни.

Хедъри

  • 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 (или произволен непрозрачен низ ≤ 64 знака) за логическа операция. Първият отговор се повтаря в продължение на 24 часа.

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

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

    string (24 hex chars)

    ID на продукта, към който принадлежи паспортът. Трябва да принадлежи на компанията на API ключа.

    e.g. 6650a1b2c3d4e5f6a7b8c9d0

  • identifier

    ProductIdentifier

    Идентификатор с маркировка на схема по EN 18219. Трябва да се посочи точно едно от identifier или легасито gs1 поле. Приема пет схеми: gs1 (GTIN + сериен номер), iso15459 (идентификатор на не-GS1 агенция), iec61406 (IEC Identification Link URI), did (W3C DID), doi (Digital Object Identifier). За doi полето granularity е ЗАДЪЛЖИТЕЛНО — трябва да е "model", "batch" или "item" (EN 18219 §5.6.2(б): DOI трябва да декларира дали идентифицира продуктовия модел, производствена партида или отделна единица). Батерийните паспорти приемат само gs1 и iso15459; iec61406, did и doi се отхвърлят съгласно чл. 77(3) от Регламента за батериите, който изисква идентификатор по ISO/IEC 15459.

  • gs1.gtin

    string (14 digits, or 13-digit EAN)

    GTIN-14 с валидна GS1 контролна цифра. Компонент на легасито gs1 поле — за нови интеграции предпочитайте identifier с scheme: "gs1". Не трябва вече да е регистриран от друг тенант.

    e.g. 04012345000016

  • gs1.serialNumber

    string (1-100 chars)

    Сериен номер, уникален в рамките на GTIN. Най-разпространеният модел е модел на продукта + последователност (BP-48V-100-000001).

    e.g. BP-48V-100-000001

  • parties

    Record<role, Party>

    Незадължителен структурен блок parties. Карта по роля — manufacturer, importer, authorisedRepresentative, distributor, recycler, producerResponsibilityOrg. Всяка стойност е Party. Виж endpoint Upsert party за формата на отделен Party. Ролите могат да бъдат добавени или заменени след създаване чрез PATCH /api/v1/passports/{id}/parties/{role}.

  • lineage

    LineageInput

    Само за паспорти на батерии. Батерия, подложена на подготовка за повторна употреба, подготовка за промяна на предназначението, промяна на предназначението или вторично производство, получава нов паспорт, свързан с паспорта или паспортите на оригиналната батерия (чл. 77(7) от Регламента за батериите). Изпратете { predecessors: [ { internalPassportId | identifier, trigger } ] } с до 10 предшественика: internalPassportId за ваш собствен паспорт, identifier (неговият разрешим URI) за всеки друг. trigger е preparation_for_reuse, preparation_for_repurposing, repurposing или remanufacturing. batteryStatus се извежда от тези стойности, блокът не може да се променя след създаване, а вашите оригинални паспорти получават връзка successors. Батерия, пусната на пазара преди 18 февруари 2027 г., няма оригинален паспорт: изпратете празен списък с noPredecessorReason. При нарушено правило отговорът е 422 с кода на правилото в error, напр. duplicate_predecessor, predecessor_not_found, status_trigger_mismatch.

Заявка

curl -sS https://app.tracepass.eu/api/v1/passports \
  -H "Authorization: Bearer tp_REDACTED_xxxxxxxxxxxx" \
  -H "Idempotency-Key: 7b4f1e2c-9a3d-4e5b-8c1a-2d3e4f5a6b7c" \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "6650a1b2c3d4e5f6a7b8c9d0",
    "gs1": {
      "gtin": "04012345000016",
      "serialNumber": "BP-48V-100-000001"
    }
  }'

Отговор

{
  "_id": "6650b2c3d4e5f6a7b8c9d0e1",
  "companyId": "6650a0b1c2d3e4f5a6b7c8d9",
  "productId": "6650a1b2c3d4e5f6a7b8c9d0",
  "templateId": "6650a1b2c3d4e5f6a7b8c9d1",
  "gs1": {
    "gtin": "04012345000016",
    "serialNumber": "BP-48V-100-000001",
    "digitalLinkUri": "https://id.tracepass.eu/p/01/04012345000016/21/BP-48V-100-000001"
  },
  "status": "draft",
  "completionPercentage": 32,
  "fieldCounts": {
    "total": 52,
    "empty": 35,
    "approved": 17,
    "pendingReview": 0,
    "flagged": 0
  },
  "fields": { "...": "...seeded from product defaults + template defaults + company prefill..." },
  "createdAt": "2026-05-09T10:00:00.000Z"
}

Свързани endpoints