---
title: "Creare il file di caricamento per l'EU DPP Registry"
description: "Il file XML che l'operatore economico carica sul sito dell'EU DPP Registry, per fino a 100 passaporti della batteria. Solo quelli idonei. A pagamento."
canonical: "https://www.tracepass.eu/it/docs/registry-upload-file"
locale: it
source: "https://www.tracepass.eu/it/docs/registry-upload-file"
---

# Creare il file di caricamento per l'EU DPP Registry

> Il file XML che l'operatore economico carica sul sito dell'EU DPP Registry, per fino a 100 passaporti della batteria. Solo quelli idonei. A pagamento.

```http
POST /api/v1/registry/upload-file
```

Crea il file XML che l'operatore economico carica sul sito web dell'EU DPP Registry (DPP Registration → upload a file) per i passaporti della **batteria** che indicate, fino a 100 per chiamata. La registrazione è un atto proprio dell'operatore con il proprio EU Login; TracePass prepara il file e non lo presenta mai.

**Entrano solo i passaporti che supererebbero il controllo.** Il registro respinge l'intero file per una sola voce errata, quindi ogni altro passaporto torna in `excluded` con il suo `reason`: `not_found`, `not_battery`, `not_published`, `registered_in_production`, `registration_in_progress` (in corso di invio a un registro EN 18222), `readiness_blocked` (i risultati bloccanti sono in `details`), `invalid_upi`, `duplicate_upi` (lo stesso indirizzo di un altro passaporto nel file) o `over_limit` (oltre il centesimo). `included` elenca i passaporti nel file, ciascuno con il suo indirizzo.

L'indirizzo di ogni passaporto incluso viene congelato nel passaporto (`registryUpi`) e la preparazione annotata (`registrationPreparedVia: "file"`). Salvate `xml` con il nome `filename` e caricatelo senza modifiche: il nome usa solo i caratteri che il registro accetta. Una preparazione non è una registrazione: annotate la risposta del registro per ogni passaporto con `POST /api/v1/passports/{id}/registration`.

La risposta è JSON anziché XML grezzo, così può essere ripetuta con `Idempotency-Key` e riporta le esclusioni. **Solo piani a pagamento** (`402` su Free). Le chiamate OAuth devono agire per un amministratore o un proprietario. Conta una scrittura v1 per ogni passaporto incluso.

## 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. |
| `passportIds` | body | string\[\] (24 hex chars each, 1–100) | yes | I passaporti da inserire nel file. Quelli che non supererebbero il controllo tornano in `excluded` invece di far fallire la chiamata. |

## Examples

```bash
curl -sS -X POST \
  https://app.tracepass.eu/api/v1/registry/upload-file \
  -H "Authorization: Bearer tp_REDACTED_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5a8d2f17-9c4e-4b3a-8e61-0f2c7d9b4e35" \
  -d '{ "passportIds": ["6650b2c3d4e5f6a7b8c9d0e1", "6650b2c3d4e5f6a7b8c9d0e2"] }'
```

```typescript
import { writeFile } from "node:fs/promises";

const res = await fetch("https://app.tracepass.eu/api/v1/registry/upload-file", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TRACEPASS_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({ passportIds }),
});
const { xml, filename, included, excluded } = await res.json();

// Upload this file unchanged on the EU DPP Registry website.
await writeFile(filename, xml);
for (const e of excluded) console.log("left out:", e.id, e.reason, e.details ?? []);
console.log(`${included.length} passport(s) in ${filename}`);
```

```python
import os, uuid, requests
res = requests.post(
    "https://app.tracepass.eu/api/v1/registry/upload-file",
    headers={
        "Authorization": f"Bearer {os.environ['TRACEPASS_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={"passportIds": passport_ids},
)
res.raise_for_status()
body = res.json()
with open(body["filename"], "w", encoding="utf-8") as f:
    f.write(body["xml"])  # upload this file unchanged
for e in body["excluded"]:
    print("left out:", e["id"], e["reason"], e.get("details", []))
```

## Responses

### 200 — File di caricamento

```json
{
  "xml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n…",
  "filename": "acme-batteries-dpp-registry-batch-2026-11-06.xml",
  "included": [
    {
      "id": "6650b2c3d4e5f6a7b8c9d0e1",
      "upi": "https://id.tracepass.eu/01/04012345000016/21/A1B2C3"
    }
  ],
  "excluded": [
    {
      "id": "6650b2c3d4e5f6a7b8c9d0e2",
      "reason": "readiness_blocked",
      "details": [
        "Required field \"Battery Carbon Footprint — Total\" has no value."
      ]
    }
  ]
}
```

### 400 — Errore di validazione

```json
{
  "error": "Validation failed",
  "details": { "passportIds": ["Too small: expected array to have >=1 items"] }
}
```

### 402 — Piano Free

```json
{ "error": "Available on every paid plan. Upgrade to use it." }
```

## Related

- [Annotare l'esito del registro](https://www.tracepass.eu/it/docs/record-passport-registration.md)
- [Indirizzo per un singolo passaporto](https://www.tracepass.eu/it/docs/passport-registry-upi.md)
- [Verificare la prontezza per il registro](https://www.tracepass.eu/it/docs/passport-registry-readiness.md)