---
title: Създаване на паспорт
description: "Създаване на един паспорт, обвързан с продукт. Уникалност GTIN + сериен номер. 402 overage_required над лимита; confirmOverage:true за приемане."
canonical: "https://www.tracepass.eu/bg/docs/create-passport"
locale: bg
source: "https://www.tracepass.eu/bg/docs/create-passport"
---

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

> Създаване на един паспорт, обвързан с продукт. Уникалност GTIN + сериен номер. 402 overage_required над лимита; confirmOverage:true за приемане.

```http
POST /api/v1/passports
```

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

GTIN трябва да е 14 цифри с валидна GS1 контролна цифра и да не е регистриран от друг тенант. Брои се като едно v1 записване И консумира един DPP слот от квотата `maxDpps` на плана — когато тази квота е изчерпана и планът ви поддържа overage, повикването връща 402 с тяло `overage_required`; повторете с `confirmOverage: true`, за да приемете таксата за паспорт.

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

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Authorization` | header | string | yes | `Bearer <token>` — или `tp_` API ключ (Developer → API Keys; най-просто, за server-to-server), или OAuth 2.0 access token (Developer → OAuth Apps; за приложения, авторизирани от потребител, scoped и отзоваеми). Страницата Authentication съдържа пълния OAuth поток и списъка със scopes. |
| `Idempotency-Key` | header | string | no | UUID v4 (или произволен непрозрачен низ ≤ 255 знака) за логическа операция. Първият отговор се повтаря в продължение на 24 часа. |
| `productId` | body | ObjectId | yes | ID на продукта, към който принадлежи паспортът. Трябва да принадлежи на компанията на API ключа. |
| `gs1.gtin` | body | string (14 digits) | yes | GTIN-14 с валидна GS1 контролна цифра. Не трябва вече да е регистриран от друг тенант. |
| `gs1.serialNumber` | body | string (1-100 chars) | yes | Сериен номер, уникален в рамките на GTIN. Най-разпространеният модел е модел на продукта + последователност (BP-48V-100-000001). |
| `parties` | body | Record<role, Party> | no | Незадължителен структурен блок parties. Карта по роля — `manufacturer`, `importer`, `authorisedRepresentative`, `distributor`, `recycler`, `producerResponsibilityOrg`. Всяка стойност е Party. Виж endpoint Upsert party за формата на отделен Party. Ролите могат да бъдат добавени или заменени след създаване чрез PATCH /api/v1/passports/{id}/parties/{role}. |
| `confirmOverage` | body | boolean | no | Приемете таксата overage за паспорт, когато квотата `maxDpps` на плана вече е изчерпана. Изисква се само след 402 отговор при предходен опит. |

## Examples

```bash
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"
    }
  }'
```

```typescript
import { randomUUID } from "node:crypto";

const res = await fetch("https://app.tracepass.eu/api/v1/passports", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TRACEPASS_API_KEY}`,
    "Idempotency-Key": randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    productId: "6650a1b2c3d4e5f6a7b8c9d0",
    gs1: {
      gtin: "04012345000016",
      serialNumber: "BP-48V-100-000001",
    },
  }),
});

if (!res.ok) throw new Error(`Create failed: ${res.status}`);
const passport = await res.json();
console.log(passport.gs1.digitalLinkUri);
```

```python
import os, uuid, requests

res = requests.post(
    "https://app.tracepass.eu/api/v1/passports",
    headers={
        "Authorization": f"Bearer {os.environ['TRACEPASS_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
        "Content-Type": "application/json",
    },
    json={
        "productId": "6650a1b2c3d4e5f6a7b8c9d0",
        "gs1": {
            "gtin": "04012345000016",
            "serialNumber": "BP-48V-100-000001",
        },
    },
)
res.raise_for_status()
passport = res.json()
print(passport["gs1"]["digitalLinkUri"])
```

## Responses

### 201 — Създаден

```json
{
  "_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"
}
```

### 400 — Валидационна грешка

```json
{
  "error": "Validation error",
  "details": {
    "fieldErrors": {
      "gs1.gtin": ["GTIN must be 14 digits"]
    }
  }
}
```

### 402 — Изисква се overage

```json
{
  "error": "overage_required",
  "planLimit": 100,
  "currentUsage": 100,
  "extraPriceCents": 75,
  "message": "DPP quota reached. Retry with { confirmOverage: true } to accept the per-passport charge."
}
```

### 409 — Конфликт

```json
// GTIN owned by another tenant
{ "error": "This GTIN is already registered by another company. Contact support if this is an error." }

// Or: serial collision within the GTIN
{ "error": "Serial number already exists for this GTIN" }
```

### 429 — Лимит

```json
{
  "error": "API rate limit: 200 writes/day via /api/v1. Currently 200 today; requested 1. Retry tomorrow (UTC) or upgrade your plan."
}
```

## Related

- [Актуализиране на едно поле](https://www.tracepass.eu/bg/docs/update-field.md)
- [Прикачване на икономически оператор](https://www.tracepass.eu/bg/docs/upsert-party.md)