---
title: Бърз старт
description: Създайте първия си паспорт за пет минути — регистрирайте се, генерирайте API ключ, публикувайте паспорт, сканирайте QR.
canonical: "https://www.tracepass.eu/bg/docs/quickstart"
locale: bg
source: "https://www.tracepass.eu/bg/docs/quickstart"
---

# Бърз старт

> Създайте първия си паспорт за пет минути — регистрирайте се, генерирайте API ключ, публикувайте паспорт, сканирайте QR.

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

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

Необходимо ви е работно пространство на TracePass на **всеки план, включително Free** — достъпът до v1 API е на всяко ниво. Само Free (100/ден) и Basic (200/ден) имат дневен лимит на заявките; Starter и по-горе са без ограничение. Регистрирайте се на [app.tracepass.eu/register](https://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.

```bash
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, след което паспортът се публикува от таблото, когато прегледът е приключен.

```bash
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": "04012345000016",
      "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 регистър).

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

### Какво следва

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

**Tip —** Третирайте всеки `POST` / `PATCH` / `DELETE` като идемпотентен, като изпращате `Idempotency-Key` header с UUID v4, генериран от вашия клиент за всяка логическа операция. Платформата повтаря оригиналния отговор в продължение на 24 часа за същия ключ, така че повторни мрежови опити са безопасни.