API overview
Quattro risorse e le relazioni tra loro
I passaporti descrivono. Gli eventi registrano. Le credenziali dimostrano. La risoluzione serve. Mettere in chiaro questi quattro prima di iniziare è ciò che evita di dover smontare un’integrazione sei mesi dopo.
- Percorso base
- /v1
- Formato
- JSON su HTTPS
- Auth
- Chiavi bearer con ambito
Definition
Com’è strutturata l’API del passaporto?
Attorno a quattro risorse. I passaporti contengono il record di prodotto e la sua policy di accesso. Gli eventi registrano che cosa è successo a un oggetto, serializzati come GS1 EPCIS 2.0. Le credenziali portano dichiarazioni firmate come W3C Verifiable Credentials. La risoluzione trasforma un identificativo GS1 Digital Link nella vista cui il chiamante ha diritto.
Each serialises somebody else’s standard — EPCIS 2.0, VC 2.0 and GS1 Digital Link — so what you build against these endpoints keeps working against a conforming implementation that is not ours.
Il modello
Quale risorsa risponde a quale domanda
| Resource | Risposte | Standard |
|---|---|---|
| Passport | "What is this product, and who may see which part?" | Modello allineato a CIRPASS |
| Event | "What happened to this object, where and when?" | GS1 EPCIS 2.0 (JSON-LD) |
| Credential | "Who asserted this, and can I check it myself?" | W3C Verifiable Credentials 2.0 |
| Resolution | "Someone scanned this — what do they get?" | GS1 Digital Link |
Endpoint
La superficie, in breve
Passaporti
Crea, leggi, aggiorna e versiona il record di prodotto. Report dei gap rispetto al gruppo di prodotti.
Eventi
Aggiungi eventi EPCIS 2.0 e interroga l’intera storia di un’identità di oggetto.
Credenziali
Emettere, presentare, verificare e revocare dichiarazioni firmate su un passaporto.
Risoluzione
Il percorso di lettura pubblico che segue una scansione, restituendo il livello adeguato al chiamante.
Autenticazione
Chiavi bearer con ambito, per ambiente e per funzionalità.
Riferimento completo
Ogni endpoint, parametro, forma di risposta e codice di errore.
Risposte
Domande frequenti
Quali sono le risorse principali dell’API?
Quattro. I passaporti contengono il record di prodotto e la sua policy di accesso. Gli eventi registrano che cosa è successo a un oggetto, serializzati come EPCIS 2.0. Le credenziali portano dichiarazioni firmate come W3C Verifiable Credentials. La risoluzione è il percorso di lettura: entra un identificativo GS1 Digital Link, esce la vista adatta al chiamante.
Quando dovrei scrivere un evento anziché aggiornare il passaporto?
Aggiornate il passaporto quando state correggendo o completando la sua descrizione. Scrivete un evento quando è successo qualcosa: una fase completata, una custodia trasferita, una riparazione eseguita. La regola pratica è che un campo del passaporto risponde a «che cos’è?» e un evento risponde a «che cosa gli è successo?».
Perché la risoluzione è una questione distinta dalla lettura di un passaporto?
Perché la risoluzione è ciò che fa una scansione, ed è pubblica, anonima e cacheabile. Leggere un passaporto tramite l’API è autenticato e restituisce ciò a cui la tua chiave dà diritto. Servono chiamanti diversi con garanzie diverse, quindi confonderli significherebbe far ereditare al percorso pubblico il costo di quello privato.
L’API è versionata?
Sì, nel percorso: tutto sta sotto `/v1`. Le modifiche additive vengono rilasciate senza cambio di versione; qualsiasi cosa romperebbe un’integrazione esistente riceve una nuova versione con un periodo di sovrapposizione. I record dei passaporti sono versionati separatamente, perché un passaporto sopravvive a qualunque versione di API con cui è stato creato.
Next step
Leggi poi il riferimento
Ora avete il modello. Il riferimento contiene lo schema, i parametri e il contratto degli errori.