Бърз старт

Пет минути от регистрация до Цифров продуктов паспорт в чернова. Това ръководство показва най-малкия възможен работещ пример — един продукт, един паспорт, без parties, без webhooks. Добавете тях, след като видите целия поток.

Преди да започнете

Необходимо ви е работно пространство на TracePass на всеки план, включително Free — достъпът до v1 API е на всяко ниво; различава се само дневният брой заявки (Free 100, Basic 200, Starter 350, Growth 500, Scale 1 000, Pro 2 000, Enterprise без ограничение). Регистрирайте се на app.tracepass.eu/register, след което се върнете тук. Примерите по-долу приемат продукционния base URL https://app.tracepass.eu; заменете със собствен хост, ако работите self-hosted.

1. Генерирайте API ключ

1. Отворете Developer → API keys в таблото.
2. Кликнете New key, задайте етикет (“Quickstart” е удачен) и копирайте тайната. Ключовете започват с префикс tp_, последван от непрозрачен случаен суфикс — съхранявайте ги във вашия secret manager, не в source control.
3. Всяко API повикване носи ключа като Bearer token в стандартнияAuthorization header. Ще го маскираме катоtp_REDACTED_xxxxxxxxxxxx навсякъде по-долу.

2. Създайте продукт

Паспортите винаги принадлежат на продукт, а продуктът е обвързан с шаблон на категория, който управлява валидацията на полетата, излъчването на JSON-LD и рендерирането на публичния преглед. Категориите са seeded — изберете slug, който отговаря на стоката ви. За батерии това е batteries; за текстил — textiles; за бижута — jewelry. Пълният списък е в публичния Buyer's Guide.

curl -sS https://app.tracepass.eu/api/v1/products \
  -H "Authorization: Bearer tp_REDACTED_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "48V Li-Ion Pack",
    "model": "BP-48V-100",
    "category": "batteries"
  }'

Отговорът 201 съдържа _id — това е handle на продукта ви. Запазете го за стъпка 3.

3. Създайте паспорт

Паспортът е една серийна единица на продукт. Задайте productId на продукта, който току-що създадохте, подайте 14-цифрен GS1 GTIN (с валидна контролна цифра) и сериен номер, уникален в рамките на GTIN. Паспортът се материализира в статус draft — полетата се попълват чрез per-field PATCH endpoint, след което паспортът се публикува от таблото, когато прегледът е приключен.

curl -sS https://app.tracepass.eu/api/v1/passports \
  -H "Authorization: Bearer tp_REDACTED_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "6650a1b2c3d4e5f6a7b8c9d0",
    "gs1": {
      "gtin": "04012345000015",
      "serialNumber": "BP-48V-100-000001"
    }
  }'

Отговорът 201 носи gs1.digitalLinkUri — GS1 Digital Link URL, който можете да кодирате в QR код още днес, дори преди паспортът да е публикуван. До публикуването URL връща 503 placeholder; след публикуването обслужва публичния преглед (HTML по подразбиране, application/ld+json при content negotiation).

4. Сканирайте QR кода

След като сте попълнили полетата и сте публикували паспорта от таблото, отворете gs1.digitalLinkUri в браузър — точно това би видял краен потребител или регулаторен мобилен скенер. Същият URL с Accept: application/ld+json връща JSON-LD документа за машинни потребители (одитори, EPREL ingestion, предстоящия EU DPP регистър).

curl -sSL https://id.tracepass.eu/p/01/04012345000015/21/BP-48V-100-000001 \
  -H "Accept: application/ld+json"

Какво следва

Сега имате един паспорт. Двете последващи стъпки, които повечето екипи изграждат след това, са: (a) прикачете икономически оператори (parties), за да премине проверката за изискваните роли на регулатора — вижте endpoint-а Upsert party; (b) свържете webhook, за да научи вашият ERP за промени в жизнения цикъл (публикуване, спиране, архивиране) — вижте раздел Webhooks.