CirculeID

Documentation

Hier beginnen

Alles, was Sie brauchen, um einen Pass auszustellen, Lieferkettenereignisse anzufügen und einen Nachweis zu prüfen — mit den Standards, auf die jedes davon abbildet, sodass nichts, was Sie bauen, an diese Plattform gebunden ist.

API-ReferenzAPI-Schlüssel holen
Protokoll
JSON über HTTPS
Ereignisse
EPCIS 2.0 JSON-LD
Nachweise
W3C VC 2.0

Definition

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

Legen Sie eine Pass-Ressource zu einer GS1-Kennung mit dem Produktdatensatz an, fügen Sie EPCIS-2.0-Ereignisse an, während sich das Produkt 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 formats are not ours: GS1 Digital Link for identity, EPCIS 2.0 for events, and W3C Verifiable Credentials for claims.

Schnelleinstieg

Ihr erster Pass

Eine authentifizierte Anfrage. Die Antwort trägt den auflösbaren Digital Link und die Trägernutzlast, 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",
    "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.

Referenz

Wie es weitergeht

Acht Seiten decken die gesamte Oberfläche ab. Sie sind in der Reihenfolge geordnet, in der eine Integration üblicherweise abläuft.

Integrationsweg

Vom API-Schlüssel zum auflösbaren Pass

Vier Schritte. Der zweite ist der einzige, der üblicherweise länger als einen Nachmittag dauert.
  1. 01

    Schlüssel mit Geltungsbereich holen

    Schlüssel sind je Umgebung und je Fähigkeit begrenzt, sodass ein Ausstellungsdienst nie Lesezugriff auf geschützte Daten hält.

  2. 02

    Den Produktdatensatz abbilden

    Senden Sie Ihren Produktstamm zu seiner GS1-Kennung. Die Antwort nennt die Felder, die die Produktgruppe noch verlangt.

  3. 03

    Ereignisse und Nachweise anfügen

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

  4. 04

    Auflösen und abonnieren

    Die Kennung löst zur aufruferangemessenen Sicht auf, und Webhooks benachrichtigen Ihre Systeme, wenn sich etwas ändert.

Antworten

Häufig gestellte Fragen

Was brauche ich, bevor ich einen Pass ausstellen kann?

Ein API-Schlüssel, eine GS1-Kennung für das Produkt und der Produktdatensatz selbst. Falls Sie noch keine GS1-Kennungen haben, ist das die erste zu klärende Abhängigkeit — sie kommen von Ihrer GS1-Mitgliedsorganisation, nicht von uns, weil die Identität außerhalb unserer Plattform global eindeutig sein muss.

Gibt es eine Sandbox?

Ja. Schlüssel sind je Umgebung gültig, Sandbox-Schlüssel können also keine Produktionspässe berühren und Produktionsschlüssel nicht versehentlich in einem Testaufbau verwendet werden. Sandbox-Pässe lösen genauso auf wie Produktionspässe, nur gegen einen getrennten Resolver-Hostnamen.

Welche Wire-Formate gibt es?

JSON über HTTPS für die API. Ereignisse folgen der GS1-EPCIS-2.0-JSON-LD-Serialisierung, Nachweise dem Datenmodell der W3C Verifiable Credentials 2.0. Wo ein Standard eine Darstellung definiert, nutzen wir sie, statt eine zu erfinden — vorhandene Werkzeuge für diese Standards funktionieren daher mit unserem Output.

Wie sollten Fehler behandelt werden?

Die API gibt übliche HTTP-Statuscodes mit einem strukturierten Fehlerkörper zurück, der das Feld und die verletzte Bedingung benennt. Validierungsfehler werden vollständig zurückgegeben statt einzeln, sodass ein fehlerhafter Produktdatensatz alle Probleme in einer Antwort zeigt statt über fünf Roundtrips.

Wie erhalten wir während der Integration Unterstützung?

Über den Support-Kanal Ihres Kontos oder über den Kontaktweg, falls Sie noch evaluieren. Integrationsfragen, die eine Lücke in der Dokumentation offenlegen, werden als Dokumentationsfehler behandelt — nur so bleibt eine Referenz korrekt, während die API wächst.

Next step

Einen Pass zu Ihrer eigenen GTIN ausstellen

Holen Sie sich einen Sandbox-Schlüssel, senden Sie einen Produktdatensatz und sehen Sie, was der zurückgegebene Träger auflöst.

API-Schlüssel holenAPI-Referenz

Index

Weiterführende Lektüre