TracePass
Inizia ora
Riferimento

Avvio rapido

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

Scarica OpenAPI 3.1Mirror JSON →

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; varia solo il limite giornaliero di chiamate (Free 100, Basic 200, Starter 350, Growth 500, Scale 1.000, Pro 2.000, Enterprise illimitato). Registratevi su 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 standardAuthorization. La mascheriamo cometp_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 productIdsul 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": "04012345000015",
      "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.digitalLinkUriin 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/04012345000015/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; (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.