CirculeID

Documentation

Parti da qui

Tutto ciò che serve per emettere un passaporto, aggiungere eventi di filiera e verificare una credenziale — con gli standard su cui ciascuna cosa si mappa, così nulla di ciò che costruisci resta prigioniero di questa piattaforma.

Riferimento APIOttieni una chiave API
Protocollo
JSON su HTTPS
Eventi
EPCIS 2.0 JSON-LD
Credenziali
W3C VC 2.0

Definition

Come si emette un passaporto digitale di prodotto tramite un’API?

Crea una risorsa passaporto su un identificativo GS1 con il record di prodotto, aggiungi eventi EPCIS 2.0 man mano che il prodotto si muove, ed emetti W3C Verifiable Credentials per le dichiarazioni che devono essere dimostrabili. La lettura risolve l’identificativo e restituisce la vista cui le credenziali del chiamante danno diritto.

The wire formats are not ours: GS1 Digital Link for identity, EPCIS 2.0 for events, and W3C Verifiable Credentials for claims.

Guida rapida

Il vostro primo passaporto

Una richiesta autenticata. La risposta porta il Digital Link risolvibile e il payload del supporto che stampi o codifichi.
POST /v1/passports
curl https://api.circuleid.com/v1/passports \
  -H "Authorization: Bearer $CIRCULEID_API_KEY" \
  -H "Content-Type: application/json" \
  -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 }
      ]
    }
  }'

Illustrative request shape. The API reference carries the authoritative schema and error contract.

Riferimento

Dove andare poi

Otto pagine coprono l’intera superficie. Sono ordinate come procede di solito un’integrazione.

Percorso di integrazione

Dalla chiave API a un passaporto risolvibile

Quattro passaggi. Il secondo è l’unico che di solito richiede più di un pomeriggio.
  1. 01

    Ottieni una chiave con ambito

    Le chiavi sono delimitate per ambiente e per funzionalità, così un servizio di emissione non ha mai accesso in lettura ai dati riservati.

  2. 02

    Mappare il record di prodotto

    Invia la tua anagrafica di prodotto sul suo identificativo GS1. La risposta indica i campi che il gruppo di prodotti richiede ancora.

  3. 03

    Aggiungere eventi e credenziali

    Scrivete eventi EPCIS 2.0 mentre l’articolo si muove; emettete credenziali per le asserzioni che devono reggere a un esame indipendente.

  4. 04

    Risolvere e sottoscrivere

    L’identificativo si risolve alla vista adatta al chiamante, e i webhook avvisano i tuoi sistemi quando qualcosa cambia.

Risposte

Domande frequenti

Che cosa mi serve prima di poter emettere un passaporto?

Una chiave API, un identificativo GS1 per il prodotto e il record di prodotto stesso. Se non hai ancora identificativi GS1, quella è la prima dipendenza da risolvere: arrivano dalla tua organizzazione membro GS1, non da noi, perché l’identità deve essere univoca a livello globale al di fuori della nostra piattaforma.

Esiste una sandbox?

Sì. Le chiavi hanno ambito per ambiente, quindi le chiavi sandbox non possono toccare passaporti di produzione e le chiavi di produzione non possono essere usate per errore in un banco di prova. I passaporti sandbox si risolvono esattamente come quelli di produzione, su un hostname del resolver separato.

Quali sono i formati di trasporto?

JSON su HTTPS per l’API. Gli eventi seguono la serializzazione JSON-LD di GS1 EPCIS 2.0, e le credenziali il modello dati W3C Verifiable Credentials 2.0. Dove uno standard definisce una rappresentazione la usiamo anziché inventarne una: gli strumenti esistenti per quegli standard funzionano quindi sul nostro output.

Come vanno gestiti gli errori?

L’API restituisce codici di stato HTTP convenzionali con un corpo di errore strutturato che indica il campo e il vincolo non soddisfatto. Gli errori di validazione sono restituiti per intero anziché uno alla volta, così un record di prodotto malformato mostra ogni problema in una sola risposta invece che in cinque round trip.

Come otteniamo supporto durante l’integrazione?

Tramite il canale di supporto del vostro account, oppure tramite il contatto se siete ancora in valutazione. Le domande di integrazione che rivelano una lacuna nella documentazione sono trattate come difetti di documentazione, che è l’unico modo perché un riferimento resti accurato mentre l’API cresce.

Next step

Emettere un passaporto sul tuo GTIN

Ottieni una chiave sandbox, invia un record di prodotto e osserva che cosa risolve il supporto restituito.

Ottieni una chiave APIRiferimento API

Index

Letture correlate