Autenticazione

TracePass v1 utilizza un solo meccanismo di autenticazione: una chiave API statica passata come bearer token nell'header standardAuthorization. Ogni operazione di scrittura accetta anche unIdempotency-Keyper nuovi tentativi sicuri. I limiti sono per piano, per giorno UTC — disponibili su ogni piano incluso Free, con limiti giornalieri di chiamate che scalano con il piano.

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"

Idempotency-Key

Ogni POST, PATCH e DELETE sulla superficie v1 accetta un header Idempotency-Key. Inviate un UUID v4 (o qualsiasi stringa opaca ≤ 255 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 restituisce422 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, per spazio di lavoro:

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 ogni GET sugli endpoint dei passaporti (lettura singola + elenco paginato). 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: 500 writes/day via /api/v1. Currently 500 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.

Una quota separata — maxDpps — limita il totale dei DPP attivi nel vostro spazio di lavoro e viene applicata tramite una risposta 402 con un corpo overage_requiredquando il piano supporta l'eccedenza per passaporto. Si veda l'endpoint Create a passport per il flusso di eccedenza.

Cosa non supportiamo (ancora)

OAuth 2.0 client-credentials, sub-chiavi con ambito e allow-listing degli IP sono tutti nella roadmap ma non ancora rilasciati. Se oggi vi serve uno di questi, generate una nuova chiave API per ogni integrazione così da poter revocare a livello di integrazione — questa è la soluzione alternativa.