CirculeID

Developers

Pässe, Ereignisse und Nachweise — über HTTP

Stellen Sie einen Pass aus, fügen Sie ein EPCIS-2.0-Ereignis an oder prüfen Sie den Nachweis eines Lieferanten — aus den Systemen, die Sie bereits betreiben. Offene Standards auf der Leitung, sodass nichts, was Sie hier bauen, gefangen ist.

Die Dokumentation lesenAPI-Referenz
Identität
GS1 Digital Link
Ereignisse
EPCIS 2.0
Aussagen
W3C VC 2.0

Definition

Wie stellt man einen digitalen Produktpass über eine API aus?

Legen Sie eine Pass-Ressource zu einer GS1-Kennung an, hängen Sie den Produktdatensatz an, fügen Sie EPCIS-2.0-Ereignisse an, während sich das Stück bewegt, und stellen Sie W3C Verifiable Credentials für belegbare Aussagen aus. Beim Lesen wird die Kennung aufgelöst und die Sicht zurückgegeben, zu der die Nachweise des Aufrufers berechtigen.

The wire format is not ours. Identity follows GS1 Digital Link, events follow EPCIS 2.0, and claims follow W3C Verifiable Credentials 2.0.

Schnelleinstieg

Einen Pass in einer Anfrage ausstellen

Senden Sie einen Produktdatensatz zu einer GS1-Kennung. Die Antwort trägt den auflösbaren Digital Link und die Datenträger-Nutzlast, die Sie drucken oder codieren.
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",
    "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" }
    }
  }'

Illustrative request shape. See the API reference for the authoritative schema and error contract.

Integrationsweg

Vom API-Schlüssel zum auflösbaren Pass

Vier Schritte. Der meiste Aufwand liegt in Schritt eins, und das ist Abbilden statt Bauen.
  1. 01

    Authentifizieren

    Legen Sie einen API-Schlüssel mit Geltungsbereich an. Schlüssel gelten je Umgebung und je Fähigkeit, sodass ein Ausstellungsdienst nie Lesezugriff auf kommerzielle Daten hält.

  2. 02

    Den Produktdatensatz abbilden

    Senden Sie Ihren vorhandenen Produktstamm zu seiner GS1-Kennung. Die API meldet, welche Felder die Produktgruppe nach ihrem delegierten Rechtsakt noch verlangt.

  3. 03

    Ereignisse und Nachweise anfügen

    Schreiben Sie EPCIS-2.0-Ereignisse, während sich der Artikel bewegt, und stellen Sie Verifiable Credentials für Aussagen aus, die einer unabhängigen Prüfung standhalten müssen.

  4. 04

    Auflösen und abonnieren

    Die Digital-Link-Kennung löst zur aufruferangemessenen Sicht auf. Webhooks benachrichtigen Ihre Systeme, wenn sich ein Pass, ein Ereignis oder ein Nachweis ändert.

Developers · 01

Aufbauen

Vom API-Schlüssel zum ausgestellten Pass.

Developers · 02

Betreiben

Eine Integration im Produktivbetrieb führen.

Antworten

Häufig gestellte Fragen

Was stellt die CirculeID-API tatsächlich aus?

Eine Pass-Ressource mit einer GS1-Digital-Link-Kennung, einer Menge daran hängender EPCIS-2.0-Ereignisse und W3C Verifiable Credentials für die Aussagen, die belegbar sein müssen. Einen Pass zu lesen heißt, die Kennung aufzulösen und die Sicht zurückzugeben, zu der der Aufrufer berechtigt ist — abhängig von den vorgelegten Nachweisen.

Müssen wir unsere Produktdaten zu CirculeID migrieren?

Nein. CirculeID steht über Ihrem ERP, PLM und Ihrer CO₂-Bilanzierung, statt sie zu ersetzen. Daten fließen über die REST-API und Webhooks ein, und der Pass wird zu einer Sicht auf Systeme, die Sie ohnehin betreiben. Die meisten Integrationen beginnen damit, einen vorhandenen Produktstamm abzubilden, statt einen zu importieren.

Wie werden Passdaten zwischen Systemen authentifiziert?

Maschine-zu-Maschine-Zugriff nutzt API-Schlüssel mit Geltungsbereich. Aussagen in einem Pass werden von der ausstellenden Partei als W3C Verifiable Credentials signiert, mit einem Decentralized Identifier, der unabhängig von CirculeID auflöst — ein nachgelagertes System kann eine Lieferantenaussage also prüfen, ohne uns überhaupt aufzurufen.

Was passiert mit unseren Pässen, wenn wir CirculeID nicht mehr nutzen?

Pässe werden in veröffentlichten Standards ausgedrückt, sodass der Datensatz auch außerhalb unserer Plattform aussagekräftig bleibt. Kennungen folgen GS1 Digital Link, Ereignisse EPCIS 2.0, Nachweise W3C Verifiable Credentials 2.0, und das Feldmodell folgt CIRPASS. Der Export liefert dieselben Dokumente, die ein anderer konformer Resolver ausliefern kann.

Next step

Gegen den Pass entwickeln, nicht gegen einen Anbieter

Holen Sie sich einen API-Schlüssel, stellen Sie einen Pass zu einer Ihrer eigenen GTINs aus und sehen Sie, was aufgelöst wird.

Die Dokumentation lesenMit einem Engineer sprechen

Index

Weiterführende Lektüre