---
title: Масово създаване на паспорти
description: "Създаване на до 100 паспорта в едно извикване. Статус per item в отговора. Същият overage flow (402 + confirmOverage:true). Поддържа Idempotency-Key."
canonical: "https://www.tracepass.eu/bg/docs/batch-create-passports"
locale: bg
source: "https://www.tracepass.eu/bg/docs/batch-create-passports"
---

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

> Създаване на до 100 паспорта в едно извикване. Статус per item в отговора. Същият overage flow (402 + confirmOverage:true). Поддържа Idempotency-Key.

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

Създаване на до 100 паспорта в едно извикване. Всеки елемент носи същата форма като endpoint-а за единично създаване (`{ productId, gs1: { gtin, serialNumber }, parties?, confirmOverage? }`). Частичен успех на елемент — всеки получава свой статус в масива на отговора.

Целият batch консумира N записвания предварително срещу дневния бюджет; ако това би прелязло, целият batch връща 429 (без частично таксуване). Същото важи за DPP overage flow на ниво batch — когато DPP квотата ще бъде надвишена, batch-ът връща 402 с `overage_required` и `confirmOverage: true` приема overage таксата за целия batch.

Idempotency-Key важи за целия batch — повтаряне на същия ключ връща оригиналния пълен резултатен масив. Лимитът е 100 елемента на повикване (съответства на batch ceiling-а на Stripe).

## 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 — важи за целия batch. |
| `passports` | body | Array<CreatePassportInput> (1-100) | yes | 1–100 обекта паспорти, всеки във формата на single-create. |

## Examples

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

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

const passports = serials.map((serial) => ({
  productId: "6650a1b2c3d4e5f6a7b8c9d0",
  gs1: { gtin: "04012345000016", serialNumber: serial },
}));

const res = await fetch("https://app.tracepass.eu/api/v1/passports/batch", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TRACEPASS_API_KEY}`,
    "Idempotency-Key": randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ passports }),
});
const { results, summary } = await res.json();
```

```python
import os, uuid, requests

passports = [
    {"productId": product_id, "gs1": {"gtin": gtin, "serialNumber": s}}
    for s in serials
]

res = requests.post(
    "https://app.tracepass.eu/api/v1/passports/batch",
    headers={
        "Authorization": f"Bearer {os.environ['TRACEPASS_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
        "Content-Type": "application/json",
    },
    json={"passports": passports},
)
res.raise_for_status()
body = res.json()
print(body["summary"])  # {created, errors, total}
```

## Responses

### 200 — Частичен успех

```json
{
  "results": [
    { "index": 0, "status": "created", "data": { "_id": "...", "gs1": { "...": "..." }, "status": "draft" } },
    { "index": 1, "status": "error", "error": "Serial number already exists for this GTIN" },
    { "index": 2, "status": "created", "data": { "...": "..." } }
  ],
  "summary": { "created": 2, "errors": 1, "total": 3 }
}
```

### 400 — Валидация

```json
{ "error": "Validation error", "hint": "Send up to 100 passports per call." }
```

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

```json
{
  "error": "overage_required",
  "planLimit": 1000,
  "currentUsage": 950,
  "requested": 100,
  "extraPriceCents": 75,
  "message": "Batch would exceed DPP quota by 50. Retry with { confirmOverage: true } to accept the overage charge."
}
```

### 429 — Лимит

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

## Related

- [Създаване на единичен паспорт](https://www.tracepass.eu/bg/docs/create-passport.md)