TracePass
Passaporti

Elencare gli snapshot del passaporto

Restituisce un elenco paginato di snapshot di immutabilità per un passaporto, dal più recente. Uno snapshot viene scritto alla pubblicazione e dopo ogni modifica di un passaporto pubblicato, sospeso, scaduto o archiviato — valori dei campi, traduzioni, parti, cambi di stato, risposte dei fornitori, scritture dell'IA, ripristini — quando il contenuto del passaporto è effettivamente cambiato (EN 18221:2026, 4.2). Ogni voce include l'id dello snapshot, il numero di versione, il motivo (ad es. published, field_edit, status_change, baseline), chi ha causato la modifica (actor, se noto), il timestamp, l'hash del contenuto e se l'hash ancora verifica — hashValid: false indica una manomissione at-rest.

GET/api/v1/passports/{id}/snapshots
Scarica OpenAPI 3.1
GET/api/v1/passports/{id}/snapshots

Elencare gli snapshot del passaporto

Restituisce un elenco paginato di snapshot di immutabilità per un passaporto, dal più recente. Uno snapshot viene scritto alla pubblicazione e dopo ogni modifica di un passaporto pubblicato, sospeso, scaduto o archiviato — valori dei campi, traduzioni, parti, cambi di stato, risposte dei fornitori, scritture dell'IA, ripristini — quando il contenuto del passaporto è effettivamente cambiato (EN 18221:2026, 4.2). Ogni voce include l'id dello snapshot, il numero di versione, il motivo (ad es. published, field_edit, status_change, baseline), chi ha causato la modifica (actor, se noto), il timestamp, l'hash del contenuto e se l'hash ancora verifica — hashValid: false indica una manomissione at-rest.

Gli snapshot portano anche restorable (se rawFields è stato catturato per consentire un ripristino a livello di campo) e fieldCount (numero di campi in rawFields, o null per snapshot solo-evidenza acquisiti prima che rawFields esistesse). I passaporti precedenti agli snapshot iniziano con uno snapshot baseline; la cronologia anteriore non è mai stata registrata.

Momento specifico: aggiungere ?at=<ISO 8601> per ottenere, invece dell'elenco, l'unico snapshot valido in quell'istante — il record completo più validFrom e validUntil (null finché è attuale). Restituisce 404 se l'istante precede il primo snapshot del passaporto.

Catena di hash. Ogni snapshot scritto dopo l'avvio della catena porta previousHash, il contentHash dello snapshot precedente (null per il primo), e hashMethod (come è stato calcolato contentHash: jcs-sha256, RFC 8785, oppure sorted-json-sha256 per gli snapshot più vecchi). Uno snapshot rimosso, inserito o modificato spezza il collegamento: ogni voce riporta chainLink (ok, broken, oppure unchained per gli snapshot precedenti alla catena), e chain riporta valid per l'intera cronologia e, se non lo è, firstBroken con lo snapshot e il motivo (hash_mismatch, previous_hash_mismatch, chain_restarted). La catena è verificata su tutti gli snapshot del passaporto, non solo sulla pagina richiesta.

Accesso delle autorità alle versioni passate. Chi ha un accesso di autorità può leggere le versioni precedenti di un passaporto sull'URL del passaporto stesso: aggiungendo ?at=<ISO 8601> (con l'accesso come ?access= o Authorization: Bearer pa_…) si ottiene la versione in vigore in quel momento, come pagina HTML o come JSON-LD; con ?versions=1 l'elenco delle versioni (data, versione, contentHash, hashMethod, previousHash, motivo, senza contenuto) con lo stesso esito chain. L'elenco è paginato: limit (default 100, al massimo 1000) e cursor (il nextCursor della pagina precedente). Una versione servita porta gli header X-TracePass-Snapshot-At, X-TracePass-Version, X-TracePass-Content-Hash, X-TracePass-Hash-Method e X-TracePass-Valid-Until. Le richieste con accesso limitato o pubblico ignorano entrambi i parametri e ricevono la versione corrente.

Scoped per tenant: sono visibili solo i passaporti della tua azienda. Conta come una lettura v1 passaporto contro il limite giornaliero. Paginare con ?page (basato su 1, default 1) e ?limit (1–100, default 20).

Parametri di percorso

  • idobbligatorio

    string (24 hex chars)

    ID del passaporto.

Parametri di query

  • page

    integer

    Numero di pagina (basato su 1, default 1).

  • at

    string (ISO 8601)

    Restituisce lo snapshot valido in quell'istante invece dell'elenco.

    e.g. 2026-09-29T12:00:00Z

  • limit

    integer

    Dimensione della pagina (1–100, default 20).

Header

  • Authorizationobbligatorio

    string

    Bearer <token> — una chiave API tp_ (Developer → API Keys; più semplice, per server-to-server) oppure un access token OAuth 2.0 (Developer → OAuth Apps; per app autorizzate dall'utente, scoped e revocabili). La pagina Authentication contiene il flusso OAuth completo e l'elenco degli scopes.

    e.g. Bearer tp_REDACTED_xxxxxxxxxxxx

Richiesta

curl -sS "https://app.tracepass.eu/api/v1/passports/6650b2c3d4e5f6a7b8c9d0e1/snapshots?limit=5" \
  -H "Authorization: Bearer tp_REDACTED_xxxxxxxxxxxx"

Risposta

{
  "entries": [
    {
      "id": "65a0f1b2c3d4e5f6a7b8c9d1",
      "version": 3,
      "reason": "republished",
      "snapshotAt": "2026-09-15T14:32:00.000Z",
      "contentHash": "sha256:a3f1c2d4e5b6a7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2",
      "hashMethod": "jcs-sha256",
      "previousHash": "sha256:b4e2d3c5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3",
      "hashValid": true,
      "chainLink": "ok",
      "restorable": true,
      "fieldCount": 142
    },
    {
      "id": "65a0f1b2c3d4e5f6a7b8c9d0",
      "version": 1,
      "reason": "published",
      "snapshotAt": "2026-08-01T09:00:00.000Z",
      "contentHash": "sha256:b4e2d3c5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3",
      "hashMethod": "sorted-json-sha256",
      "hashValid": true,
      "chainLink": "unchained",
      "restorable": false,
      "fieldCount": null
    }
  ],
  "total": 2,
  "page": 1,
  "limit": 20,
  "totalPages": 1,
  "chain": { "valid": true }
}