---
title: Pässe im Batch erstellen
description: "Bis zu 100 Pässe in einem Aufruf erstellen. Pro-Item-Status in der Antwort. Gleicher Overage-Flow (402 + confirmOverage:true). Idempotency-Key unterstützt."
canonical: "https://www.tracepass.eu/de/docs/batch-create-passports"
locale: de
source: "https://www.tracepass.eu/de/docs/batch-create-passports"
---

# Pässe im Batch erstellen

> Bis zu 100 Pässe in einem Aufruf erstellen. Pro-Item-Status in der Antwort. Gleicher Overage-Flow (402 + confirmOverage:true). Idempotency-Key unterstützt.

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

Erstellt bis zu 100 Pässe in einem Aufruf. Jedes Element trägt dieselbe Body-Form wie die Einzel-Create-Endpoint (`{ productId, gs1: { gtin, serialNumber }, parties?, confirmOverage? }`). Teilerfolg pro Element — jedes bekommt seinen eigenen Status im Antwort-Array.

Der gesamte Batch verbraucht N Schreibvorgänge vorab gegen das Tages-Schreib-Budget; wenn das überlaufen würde, gibt der gesamte Batch 429 zurück (keine Teil-Abrechnung). Gleiches gilt für den DPP-Overage-Flow auf Batch-Ebene — wenn das DPP-Kontingent überschritten würde, gibt der Batch 402 mit `overage_required` zurück und `confirmOverage: true` akzeptiert die Overage-Gebühr für den gesamten Batch.

Idempotency-Key gilt für den gesamten Batch — wiederholtes Senden mit demselben Schlüssel liefert das ursprüngliche vollständige Ergebnis-Array. Limit ist 100 Elemente pro Aufruf (entspricht Stripes Batch-Cap).

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Authorization` | header | string | yes | `Bearer <token>` — entweder ein `tp_` API-Schlüssel (Developer → API Keys; am einfachsten, für Server-zu-Server) oder ein OAuth-2.0-Access-Token (Developer → OAuth Apps; für nutzerautorisierte Apps, scoped und widerrufbar). Die Authentication-Seite enthält den vollständigen OAuth-Flow und die Scope-Liste. |
| `Idempotency-Key` | header | string | no | UUID v4 — gilt für den gesamten Batch. |
| `passports` | body | Array<CreatePassportInput> (1-100) | yes | 1–100 Pass-Objekte, jeweils in der Single-Create-Body-Form. |

## 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 — Teilerfolg

```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 — Validierung

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

### 402 — Overage erforderlich

```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 — Rate-Limit

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

## Related

- [Einzelnen Pass anlegen](https://www.tracepass.eu/de/docs/create-passport.md)