---
title: Avvio rapido
description: Create il vostro primo passaporto in cinque minuti — registratevi, generate una chiave API, pubblicate un passaporto, scansionate il QR.
canonical: "https://www.tracepass.eu/it/docs/quickstart"
locale: it
source: "https://www.tracepass.eu/it/docs/quickstart"
---

# Avvio rapido

> Create il vostro primo passaporto in cinque minuti — registratevi, generate una chiave API, pubblicate un passaporto, scansionate il QR.

Cinque minuti dalla registrazione a un passaporto digitale di prodotto in bozza. Questa guida fornisce il più piccolo esempio funzionante possibile — un prodotto, un passaporto, nessuna parte, nessun webhook. Aggiungeteli una volta che avete visto il ciclo completo.

## Prima di iniziare

Vi serve uno spazio di lavoro TracePass su **qualsiasi piano, incluso Free** — l'accesso all'API v1 è disponibile su ogni livello. Solo Free (100/giorno) e Basic (200/giorno) hanno un limite giornaliero di chiamate; Starter e superiori sono illimitati. Registratevi su [app.tracepass.eu/register](https://app.tracepass.eu/register), poi tornate qui. Gli esempi qui sotto presuppongono il base URL di produzione `https://app.tracepass.eu`; sostituitelo con il vostro host se eseguite in self-hosted.

## 1\. Generare una chiave API

1. Aprite **Developer → API keys** nella dashboard.
2. Cliccate su **New key**, assegnatele un'etichetta (“Quickstart” va bene) e copiate il secret. Le chiavi iniziano con il prefisso `tp_` seguito da un suffisso casuale opaco — conservatele nel vostro secret manager, non nel controllo di versione.
3. Ogni chiamata API porta la chiave come bearer token nell'header standard`Authorization`. La mascheriamo come`tp_REDACTED_xxxxxxxxxxxx` ovunque qui sotto.

## 2\. Creare un prodotto

I passaporti appartengono sempre a un prodotto, e un prodotto è vincolato a un template di categoria che governa la convalida dei campi, l'emissione di JSON-LD e il rendering del visualizzatore pubblico. Le categorie sono preconfigurate — scegliete lo slug che corrisponde alla vostra merce. Per le batterie è `batteries`; per i tessili, `textiles`; per la gioielleria, `jewelry`. L'elenco completo è nella Buyer's Guide pubblica.

```bash
curl -sS https://app.tracepass.eu/api/v1/products \
  -H "Authorization: Bearer tp_REDACTED_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "48V Li-Ion Pack",
    "model": "BP-48V-100",
    "category": "batteries"
  }'
```

La risposta 201 include un `_id` — è l'handle del vostro prodotto. Conservatelo per il passaggio 3.

## 3\. Creare un passaporto

Un passaporto è un'unità serializzata di un prodotto. Impostate `productId` sul prodotto appena creato, fornite un GS1 GTIN di 14 cifre (con cifra di controllo valida) più un numero di serie univoco all'interno del GTIN. Il passaporto si materializza in stato `draft` — i campi vengono popolati tramite l'endpoint PATCH per singolo campo, poi il passaporto viene pubblicato dalla dashboard una volta completata la revisione.

```bash
curl -sS https://app.tracepass.eu/api/v1/passports \
  -H "Authorization: Bearer tp_REDACTED_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "6650a1b2c3d4e5f6a7b8c9d0",
    "gs1": {
      "gtin": "04012345000016",
      "serialNumber": "BP-48V-100-000001"
    }
  }'
```

La risposta 201 porta `gs1.digitalLinkUri` — l'URL GS1 Digital Link che potete codificare in un codice QR già oggi, anche prima che il passaporto sia pubblicato. Fino alla pubblicazione l'URL restituisce un placeholder 503; dopo la pubblicazione serve il visualizzatore pubblico (HTML per impostazione predefinita, `application/ld+json` su content negotiation).

## 4\. Scansionare il codice QR

Dopo aver compilato i campi e pubblicato il passaporto dalla dashboard, aprite `gs1.digitalLinkUri` in un browser — è esattamente ciò che renderizzerebbe un consumatore finale o lo scanner mobile di un'autorità di regolamentazione. Lo stesso URL con `Accept: application/ld+json` restituisce il documento JSON-LD per i consumatori automatici (revisori, ingestione EPREL, l'imminente registro DPP dell'UE).

```bash
curl -sSL https://id.tracepass.eu/p/01/04012345000016/21/BP-48V-100-000001 \
  -H "Accept: application/ld+json"
```

### Cosa fare dopo

Ora avete un passaporto. I due passi successivi che la maggior parte dei team realizza subito dopo sono: (a) collegare le parti operatori economici affinché la verifica dei ruoli obbligatori dell'autorità di regolamentazione venga superata — si veda l'endpoint [Upsert party](/it/docs/upsert-party); (b) collegare un webhook affinché il vostro ERP venga a conoscenza delle modifiche del ciclo di vita (pubblicazione, sospensione, archiviazione) — si veda la sezione [Webhooks](/it/docs/webhooks).

**Tip —** Trattate ogni `POST` / `PATCH` / `DELETE` come idempotente inviando un header `Idempotency-Key` con un UUID v4 generato dal vostro client per ogni operazione logica. La piattaforma riproduce la risposta originale per 24 ore con la stessa chiave, quindi un nuovo tentativo di rete è sicuro.