Autenticazione

TracePass v1 supporta due metodi di autenticazione. Una chiave API (un bearer token statico) è il più semplice — ideale per integrazioni server-to-server ed ERP. OAuth 2.0 con PKCE è per app di terze parti e assistenti AI che agiscono per conto di un utente con accesso scoped e revocabile. Entrambi arrivano come bearer token nell'header standard Authorization; la maggior parte delle route di scrittura accetta anche un Idempotency-Key per nuovi tentativi sicuri. Disponibili su ogni piano incluso Free. I limiti giornalieri si applicano solo a Free (100 scritture + 100 letture di passaporti per chiave API) e Basic (200 + 200); Starter e superiori sono illimitati.

Chiavi API

Generate le chiavi in Developer → API keys nella dashboard. Le chiavi sono associate allo spazio di lavoro: ogni chiave è legata a uno spazio di lavoro e ne eredita il piano, i limiti e la traccia di controllo. Le chiavi portano il prefisso tp_ seguito da un suffisso casuale opaco — non esiste un prefisso live / test separato, né una sandbox con namespace per ambiente. Effettuate i test sul vostro spazio di lavoro Free o Basic se vi serve un ambiente non di produzione.

Passate la chiave come bearer token su ogni richiesta:

curl -sS https://app.tracepass.eu/api/v1/products \
  -H "Authorization: Bearer tp_REDACTED_xxxxxxxxxxxx"

OAuth 2.0 (app autorizzate dall'utente)

Quando costruite un'app che altri utenti TracePass collegano — o un assistente AI che un utente autorizza — usate OAuth 2.0 invece di chiedere loro di incollare una chiave API. L'utente approva scopes specifici su una schermata di consenso; il token di accesso che genera è limitato all'intersezione tra il suo ruolo nella dashboard e gli scopes concessi. Registrate la vostra app in Developer → OAuth Apps (o a livello programmatico tramite Dynamic Client Registration su /api/oauth/register). Supportiamo l' authorization-code flow con PKCE — i client pubblici (SPA / mobile / MCP) non hanno bisogno di un secret; i client server-side confidenziali ne ricevono uno.

Il flusso

I metadati di discovery si trovano su /.well-known/oauth-authorization-server (RFC 8414). In breve: (1) indirizzate l'utente a /api/oauth/authorize con il vostro client_id, redirect_uri, lo scope richiesto, state e un code_challenge PKCE (S256); (2) l'utente approva e noi reindirizziamo indietro con un code monouso; (3) scambiatelo su /api/oauth/token con il vostro code_verifier per un token di accesso di 15 minuti (più un refresh token se è stato concesso offline_access). I refresh token ruotano a ogni uso; revocate su /api/oauth/revoke (RFC 7009).

Scopes

Richiedete solo ciò di cui la vostra app ha bisogno — la schermata di consenso mostra all'utente esattamente questi. Uno scope di scrittura richiede inoltre che l'utente autorizzante abbia un ruolo nella dashboard con permessi di scrittura, quindi un viewer che concede passports:write comunque non può scrivere. Le chiavi API, al contrario, sono „tutto o niente“ e ignorano gli scopes.

Idempotency-Key

Route di scrittura v1 selezionate accettano un header Idempotency-Key — prodotti (crea, batch, aggiorna, elimina, archivia), passaporti (crea, batch, aggiorna, archivia, sospendi, aggiornamento campo, aggiornamento parte, flag di condizione, acquisizione misurazione), acquisizione EPCIS e avvii del catalogo scope. Inviate un UUID v4 (o qualsiasi stringa opaca ≤ 64 caratteri) per ogni operazione logica; la piattaforma memorizza la prima risposta per 24 ore e la riproduce se la stessa chiave + lo stesso spazio di lavoro si ripresentano. I nuovi tentativi di rete diventano sicuri — non creerete un passaporto in doppio perché il vostro client HTTP ha ritentato su un 5xx transitorio.

curl -sS https://app.tracepass.eu/api/v1/passports \
  -H "Authorization: Bearer tp_REDACTED_xxxxxxxxxxxx" \
  -H "Idempotency-Key: 7b4f1e2c-9a3d-4e5b-8c1a-2d3e4f5a6b7c" \
  -H "Content-Type: application/json" \
  -d '{ "productId": "...", "gs1": { "gtin": "...", "serialNumber": "..." } }'

Riutilizzare la stessa chiave con un corpo della richiesta diverso restituisce 422 Unprocessable Entity con error: "Idempotency-Key has already been used with a different request body. Use a new key for the new request, or reuse the original body." — la piattaforma non sovrascrive silenziosamente, perché si tratta quasi sempre di un bug del client. Generate una chiave nuova per operazioni effettivamente nuove.

Limiti di frequenza

Si applicano due soglie per giorno UTC, conteggiate per chiave API (un'app OAuth ha il proprio conteggio):

1. Budget di scrittura v1 — `maxV1WritesPerDay`

Conta ogni POST / PATCH / DELETE sulla superficie v1. Le letture non vengono conteggiate su questo contatore.

2. Budget di lettura passaporti v1 — `maxV1PassportsPerDay`

Conta i passaporti letti: una chiamata di elenco conta la dimensione della sua pagina (limit, predefinito 20), anche quando l'ultima pagina ne restituisce meno; ogni altra lettura conta 1 (un singolo passaporto, il suo codice QR, gli snapshot, il documento EPCIS, il controllo di conformità e la prontezza per il registro, oltre a interrogazione EPCIS, un lavoro di acquisizione EPCIS e il catalogo dell'ambito). Separato dal budget di scrittura, così un ERP che invia aggiornamenti non esaurisce la vostra quota di lettura e viceversa.

Quando raggiungete una delle due soglie la risposta è 429 Too Many Requests con un corpo del tipo { "error": "API rate limit: 200 writes/day via /api/v1. Currently 200 today; requested 1. Retry tomorrow (UTC) or upgrade your plan." }. La finestra si reimposta alle 00:00 UTC; non supportiamo finestre scorrevoli perché rendono il limite più difficile da interpretare a valle.

Un limite separato — maxDpps — limita il numero di passaporti pubblicati nel vostro spazio di lavoro. Un passaporto creato tramite l'API è una bozza e non occupa posti, quindi la creazione non restituisce mai un errore di eccedenza. Il limite si applica quando pubblicate dalla dashboard. Oltre il limite, la dashboard vi chiede di confermare l'addebito di eccedenza per passaporto, oppure rifiuta se il piano non prevede una tariffa di eccedenza; in quel caso fate un upgrade o archiviate dei passaporti. Si veda l'endpoint Create a passport.

Cosa non supportiamo (ancora)

Il grant OAuth client-credentials (identità macchina senza utente) e l'allow-listing degli IP sono nella roadmap ma non ancora rilasciati. Per il puro accesso server-to-server oggi usate una chiave API — generatene una per ogni integrazione così da poter revocare a livello di integrazione.