API reference
Jeder Endpunkt, nach Ressource gruppiert
Pässe, Ereignisse, Nachweise und Auflösung. Der Fehlervertrag sowie die Paginierungs- und Idempotenzregeln unten gelten einheitlich für alle vier.
- Basis-URL
- api.circuleid.com
- Version
- /v1
- Auth
- Bearer
Definition
Welche Endpunkte stellt die Pass-API bereit?
Vier Gruppen. Pass-Endpunkte stellen den Produktdatensatz aus, lesen, aktualisieren und versionieren ihn. Ereignis-Endpunkte fügen EPCIS-2.0-Lieferkettenereignisse an und fragen sie ab. Nachweis-Endpunkte stellen signierte Aussagen aus, prüfen und widerrufen sie. Auflösungs-Endpunkte bedienen den öffentlichen GS1-Digital-Link-Pfad, dem ein gescannter Datenträger folgt.
If you have not read the API model yet, start there. The relationships between these four decide which one you should be calling, and that is the choice most integrations get wrong first.
Endpunkte
Pässe
| Methode | Path | Purpose |
|---|---|---|
| POST | /v1/passports | Issue a passport against a GS1 identifier |
| GET | /v1/passports/{id} | Read the full record your key is entitled to |
| PATCH | /v1/passports/{id} | Update the record; material changes are versioned |
| GET | /v1/passports/{id}/gaps | Fields the product group’s delegated act still requires |
| GET | /v1/passports/{id}/versions | The record’s version history |
| GET | /v1/passports | List and filter passports in your tenant |
Endpunkte
Ereignisse
| Methode | Path | Purpose |
|---|---|---|
| POST | /v1/events | Append one EPCIS 2.0 event |
| POST | /v1/events/bulk | Asynchronous bulk ingestion; returns a job |
| GET | /v1/events | Query by object identity, business step or time |
| GET | /v1/jobs/{id} | Status of a bulk ingestion job |
Endpunkte
Nachweise
| Methode | Path | Purpose |
|---|---|---|
| POST | /v1/credentials | Issue a signed claim against a passport |
| GET | /v1/credentials/{id} | Retrieve a credential and its status |
| POST | /v1/credentials/{id}/revoke | Revoke; verification fails from this point |
| POST | /v1/credentials/verify | Verify a credential you were presented |
Endpunkte
Auflösung
| Methode | Path | Purpose |
|---|---|---|
| GET | /01/{gtin} | GS1 Digital Link resolution — the path a scan takes |
| GET | /01/{gtin}/21/{serial} | Resolution for an item-level passport |
Konventionen
Fehler, Paginierung und Idempotenz
# Validation errors return every problem at once.
HTTP/1.1 422 Unprocessable Entity
{
"error": "validation_failed",
"problems": [
{ "field": "materials[0].share", "constraint": "must sum to 1.0" },
{ "field": "carbonFootprint.method", "constraint": "required for this group" }
]
}
# Pagination is cursor-based: an offset would skip or repeat
# records as new events arrive while you are reading.
GET /v1/events?object=01/09506000134352&cursor=ev_8f21...
# Send an idempotency key on any write you might retry.
POST /v1/passports
Idempotency-Key: 6f1c9a7e-... # a repeat returns the original resultAntworten
Häufig gestellte Fragen
Wie sieht eine Fehlerantwort aus?
Ein üblicher HTTP-Status mit strukturiertem Body, der den Fehler, das fehlgeschlagene 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 wird paginiert?
Cursor-basiert, nicht offset-basiert. Ereignishistorien wachsen, während Sie sie lesen, und ein Offset würde beim Eintreffen neuer Ereignisse stillschweigend Datensätze überspringen oder wiederholen. Der Cursor ist undurchsichtig und stabil; übergeben Sie den der vorherigen Seite und hören Sie auf, wenn keiner mehr zurückkommt.
Sind Schreibvorgänge idempotent?
Können sie sein, und sollten sie sein. Senden Sie bei jedem Schreibvorgang, den Sie eventuell wiederholen, einen Idempotency-Key mit; eine Wiederholung mit demselben Schlüssel liefert das ursprüngliche Ergebnis zurück, statt einen zweiten Pass oder ein doppeltes Ereignis anzulegen. Ohne ihn lässt ein Netzwerk-Timeout beim Schreiben offen, ob der Vorgang angekommen ist.
Was ist der Unterschied zwischen einen Pass lesen und einen Pass auflösen?
Das Lesen ist authentifiziert und liefert, wozu Ihr API-Schlüssel berechtigt. Das Auflösen ist, was ein Scan tut: öffentlich, anonym, cachebar und die Stufe liefernd, die die Nachweise des Aufrufers erlauben — für die meisten die öffentliche Stufe. Es sind getrennte Pfade mit anderen Leistungs- und Datenschutzeigenschaften.
Next step
Einen mit einem Sandbox-Schlüssel ausstellen
Der schnellste Weg, eine API zu beurteilen, ist, ihr einen echten Produktdatensatz zu senden und zu lesen, was zurückkommt.