CirculeID

Examples

Le cinque richieste che un’integrazione fa davvero

Emettere un passaporto. Aggiungere un evento. Firmare una dichiarazione di un fornitore. Verificarne una. Servire una scansione. La maggior parte delle integrazioni è questo, ripetuto: tutto il resto è mappatura.

Ottieni una chiave sandboxRiferimento API
Parti da
Emettere + aggiungere
Aggiungere più avanti
Dichiarazioni firmate
Ambiente
Prima la sandbox

Definition

Che cosa fa davvero una tipica integrazione di passaporti?

Cinque operazioni, ripetute. Emettere un passaporto su un identificativo GS1. Aggiungere eventi EPCIS 2.0 man mano che il prodotto si muove. Raccogliere dichiarazioni firmate dai fornitori. Verificare una dichiarazione che ti viene presentata. E servire la vista pubblica quando qualcuno scansiona il supporto sul prodotto.

The volume is dominated by the first two. The difficulty is dominated by the third, which is a supplier relationship problem rather than a technical one.

01

Emettere un passaporto

Invia il record di prodotto sul suo identificativo GS1. La risposta porta il Digital Link risolvibile, il payload del supporto e il report dei gap per il gruppo di prodotti.
POST /v1/passports
curl https://api.circuleid.com/v1/passports \
  -H "Authorization: Bearer $CIRCULEID_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "gtin": "09506000134352",
    "productGroup": "textiles",
    "level": "model",
    "record": {
      "name": "Merino Crew Knit",
      "materials": [
        { "name": "merino wool", "share": 0.82, "certification": "RWS" },
        { "name": "recycled polyamide", "share": 0.18 }
      ],
      "carbonFootprint": { "value": 14.2, "unit": "kgCO2e", "method": "ISO 14067" }
    }
  }'

02

Aggiungere un evento di filiera

EPCIS 2.0 nella sua serializzazione JSON-LD. Quale oggetto, quando, dove e quale fase di processo: le quattro dimensioni cui ogni evento risponde.
POST /v1/events
curl https://api.circuleid.com/v1/events \
  -H "Authorization: Bearer $CIRCULEID_API_KEY" \
  -d '{
    "type": "ObjectEvent",
    "action": "OBSERVE",
    "eventTime": "2026-03-14T09:22:00+01:00",
    "epcList": ["urn:epc:id:sgtin:0950600.013435.SN8817403"],
    "bizStep": "urn:epcglobal:cbv:bizstep:commissioning",
    "disposition": "urn:epcglobal:cbv:disp:active",
    "bizLocation": { "id": "urn:epc:id:sgln:0950600.00001.0" }
  }'

03

Firmare una dichiarazione di un fornitore

Emessa dal fornitore sotto il proprio identificativo decentralizzato, così la dichiarazione porta il proprio autore. È questo a trasformare un valore memorizzato in una prova.
POST /v1/credentials
curl https://api.circuleid.com/v1/credentials \
  -H "Authorization: Bearer $SUPPLIER_API_KEY" \
  -d '{
    "type": "RecycledContentCredential",
    "issuer": "did:web:mill.example.com",
    "subject": "01/09506000134352",
    "validUntil": "2027-03-14T00:00:00Z",
    "claim": {
      "material": "polyamide",
      "recycledShare": 0.18,
      "basis": "mass",
      "chainOfCustody": "mass-balance"
    }
  }'

04

Verificare un’asserzione che vi è stata presentata

La verifica controlla la firma e lo stato di revoca. Non richiede CirculeID: questo endpoint è una comodità, non una dipendenza.
POST /v1/credentials/verify
curl https://api.circuleid.com/v1/credentials/verify \
  -H "Authorization: Bearer $CIRCULEID_API_KEY" \
  -d '{ "credential": { /* the credential as presented */ } }'

# {
#   "verified": true,
#   "issuer":   "did:web:mill.example.com",
#   "issuedAt": "2026-03-14T09:31:02Z",
#   "status":   "active"        # "revoked" fails verification
# }

05

Servire una scansione

Il percorso pubblico. Nessuna chiave, nessun account e la stessa risposta per ogni chiamante anonimo: per questo può essere messo in cache all’edge.
GET /01/{gtin}
# What the phone requests when a consumer scans the carrier:
curl https://id.circuleid.com/01/09506000134352 \
  -H "Accept: application/json"

# A browser gets the rendered public passport instead.
# A verified recycler presenting a credential gets the treatment tier
# from the same URL — the resolver decides, not the caller.

Modelli ricorrenti

Dove si trova di solito ciascuno

Le stesse cinque operazioni, collocate nei sistemi che di norma le presidiano.

  • Pipeline di emissione

    Un job pianificato che legge il PLM ed emette i passaporti per il lotto di produzione successivo.

  • Ingestione degli eventi

    Un servizio che traduce i messaggi WMS e MES in eventi EPCIS via via che si verificano.

  • Portale fornitori

    Dove i fornitori di secondo livello inviano e firmano le asserzioni che voi non potete fare in prima persona.

  • Vetrina

    Leggere il livello pubblico per mostrare dati di sostenibilità documentati in una scheda.

  • Il supporto stesso

    Nessun tuo codice: il resolver serve la scansione direttamente.

  • Accettazione dei resi

    Leggere il livello di trattamento sulla linea di un impianto di resi o di riciclo.

Risposte

Domande frequenti

Da quale esempio dovrei partire?

Emettere un passaporto, poi aggiungere un evento. Queste due operazioni coprono la maggior parte del traffico di un’integrazione e ti obbligano a fissare il modello di identità — modello, lotto o oggetto — che è la decisione da cui dipende tutto il resto e la più difficile da cambiare dopo.

Devo gestire credenziali fin dal primo giorno?

No. Un passaporto con dati non firmati resta un passaporto funzionante; semplicemente non può dimostrare chi abbia affermato ciascun valore. La maggior parte dei programmi emette prima e aggiunge le dichiarazioni firmate dei fornitori man mano che questi si integrano, che è anche l’ordine realisticamente consentito dal coinvolgimento dei fornitori.

Che cosa riceve davvero il consumatore da una scansione?

Il livello pubblico del passaporto, risolto dall’identificatore GS1 Digital Link nel supporto, reso come pagina per un browser o restituito in JSON a un sistema che lo richiede. Nessuna autenticazione, nessun account e nessun profilo della persona che scansiona.

Possiamo fare test senza toccare la produzione?

Sì. Le chiavi sandbox si risolvono su un hostname separato, e i passaporti sandbox si comportano esattamente come quelli di produzione. Poiché un passaporto di produzione è un artefatto pubblico di lunga durata, la separazione è imposta e non convenzionale: una chiave sandbox semplicemente non raggiunge la produzione.

Next step

Fai girare le prime due con una chiave sandbox

Emetti un passaporto e aggiungi un evento. Basta questo per fissare il modello di identità, la decisione su cui poggia tutto il resto.

Ottieni una chiave sandboxRiferimento API

Index

Letture correlate