---
title: Creazione massiva di passaporti
description: "Crea fino a 100 passaporti in una chiamata. Stato per item nella risposta. Stesso flusso overage (402 + confirmOverage:true). Idempotency-Key supportato."
canonical: "https://www.tracepass.eu/it/docs/batch-create-passports"
locale: it
source: "https://www.tracepass.eu/it/docs/batch-create-passports"
---

# Creazione massiva di passaporti

> Crea fino a 100 passaporti in una chiamata. Stato per item nella risposta. Stesso flusso overage (402 + confirmOverage:true). Idempotency-Key supportato.

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

Create fino a 100 passaporti in una sola chiamata. Ogni elemento porta la stessa forma del corpo dell'endpoint di creazione singola (`{ productId, gs1: { gtin, serialNumber }, parties?, confirmOverage? }`). Successo parziale per elemento — ognuno ottiene il proprio stato nell'array di risposta.

L'intero lotto consuma in anticipo N scritture rispetto al vostro budget di scrittura giornaliero; se ciò provocasse uno sforamento, l'intero lotto restituisce 429 (nessun addebito parziale). Lo stesso vale per il flusso di eccedenza DPP a livello di lotto — quando la quota DPP verrebbe superata, il lotto restituisce 402 con `overage_required` e `confirmOverage: true` accetta l'addebito di eccedenza per l'intero lotto.

Idempotency-Key si applica all'intero lotto — riproporre la stessa chiave restituisce l'array di risultati completo originale. Il limite è di 100 elementi per chiamata (corrisponde al tetto dei lotti di Stripe così che le risposte a successo parziale restino gestibili).

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Authorization` | header | string | yes | `Bearer <token>` — una chiave API `tp_` (Developer → API Keys; più semplice, per server-to-server) oppure un access token OAuth 2.0 (Developer → OAuth Apps; per app autorizzate dall'utente, scoped e revocabili). La pagina Authentication contiene il flusso OAuth completo e l'elenco degli scopes. |
| `Idempotency-Key` | header | string | no | UUID v4 — si applica all'intero lotto. |
| `passports` | body | Array<CreatePassportInput> (1-100) | yes | 1–100 oggetti passaporto, ciascuno nella forma del corpo di creazione singola. |

## 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 — Successo parziale

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

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

### 402 — Eccedenza richiesta

```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 — Limite di frequenza

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

## Related

- [Creare un singolo passaporto](https://www.tracepass.eu/it/docs/create-passport.md)