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. 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, 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 è battery; per i tessili, textile; 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": "battery"
  }'

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 (un EAN di 13 cifre viene completato a 14; 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
# Your own passport — substitute the gtin + serialNumber you sent in step 3.
curl -sSL https://id.tracepass.eu/p/01/04012345000016/21/BP-48V-100-000001 \
  -H "Accept: application/ld+json"

# Or run this as-is: a live sample passport, no account needed.
curl -sSL https://id.tracepass.eu/p/01/99999999999997/21/6B27A0000001 \
  -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.