API overview
Vier Ressourcen und die Beziehungen zwischen ihnen
Pässe beschreiben. Ereignisse erfassen. Nachweise belegen. Die Auflösung liefert aus. Diese vier vorab sauber zu trennen, verhindert, dass eine Integration nach sechs Monaten zurückgebaut werden muss.
- Basispfad
- /v1
- Format
- JSON über HTTPS
- Auth
- Bearer-Schlüssel mit Geltungsbereich
Definition
Wie ist die Pass-API strukturiert?
Rund vier Ressourcen. Pässe halten den Produktdatensatz und seine Zugriffsrichtlinie. Ereignisse erfassen, was einem Objekt widerfuhr, serialisiert als GS1 EPCIS 2.0. Nachweise tragen signierte Aussagen als W3C Verifiable Credentials. Die Auflösung macht aus einer GS1-Digital-Link-Kennung die Sicht, zu der ein Aufrufer berechtigt ist.
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.
Das Modell
Welche Ressource welche Frage beantwortet
| Resource | Antworten | Standard |
|---|---|---|
| Passport | "What is this product, and who may see which part?" | CIRPASS-konformes Modell |
| 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 |
Endpunkte
Die Oberfläche, kurz gefasst
Pässe
Produktdatensatz anlegen, lesen, aktualisieren und versionieren. Lückenberichte gegen die Produktgruppe.
Ereignisse
EPCIS-2.0-Ereignisse anfügen und die vollständige Historie einer Objektidentität abfragen.
Nachweise
Signierte Aussagen zu einem Pass ausstellen, vorlegen, prüfen und widerrufen.
Auflösung
Der öffentliche Lesepfad, den ein Scan nimmt und der die für die aufrufende Seite passende Stufe zurückgibt.
Authentifizierung
Bearer-Schlüssel mit Geltungsbereich, je Umgebung und je Fähigkeit.
Vollständige Referenz
Jeder Endpunkt, jeder Parameter, jede Antwortstruktur und jeder Fehlercode.
Antworten
Häufig gestellte Fragen
Was sind die Kernressourcen der API?
Vier. Pässe halten den Produktdatensatz und seine Zugriffsrichtlinie. Ereignisse erfassen, was einem Objekt widerfuhr, serialisiert als EPCIS 2.0. Nachweise tragen signierte Aussagen als W3C Verifiable Credentials. Die Auflösung ist der Lesepfad: eine GS1-Digital-Link-Kennung hinein, die aufruferangemessene Sicht hinaus.
Wann sollte ich ein Ereignis schreiben statt den Pass zu aktualisieren?
Aktualisieren Sie den Pass, wenn Sie seine Beschreibung korrigieren oder vervollständigen. Schreiben Sie ein Ereignis, wenn etwas passiert ist — ein Schritt abgeschlossen, die Obhut übergeben, eine Reparatur durchgeführt. Als Faustregel gilt: Ein Passfeld beantwortet „Was ist das?“, ein Ereignis beantwortet „Was ist damit geschehen?“.
Warum ist die Auflösung etwas anderes als das Lesen eines Passes?
Weil Auflösung das ist, was ein Scan tut — öffentlich, anonym und cachebar. Einen Pass über die API zu lesen, ist authentifiziert und liefert, wozu Ihr Schlüssel berechtigt. Sie bedienen verschiedene Aufrufer mit verschiedenen Zusagen; sie zu vermischen hieße, dem öffentlichen Weg die Kosten des privaten aufzubürden.
Ist die API versioniert?
Ja, im Pfad — alles liegt unter `/v1`. Additive Änderungen gehen ohne Versionssprung live; alles, was eine bestehende Integration brechen würde, bekommt eine neue Version mit Übergangszeitraum. Passdatensätze selbst werden getrennt versioniert, weil ein Pass jede API-Version überlebt, unter der er entstanden ist.
Next step
Als Nächstes die Referenz lesen
Sie haben jetzt das Modell. Die Referenz enthält das Schema, die Parameter und den Fehlerkontrakt.