TracePass
Loslegen
EPCIS 2.0

EPCIS-Ereignisse erfassen

Die GS1-EPCIS-2.0-Capture-Schnittstelle. Übermitteln Sie Lieferketten-Ereignisse von Partnern, ERP-Systemen oder Werkstatt-Scannern, und TracePass hängt sie an die passenden Pässe an. Der Request-Body akzeptiert vier Formen: ein vollständiges EPCISDocument, ein EPCISQueryDocument, ein einzelnes nacktes Event oder ein nacktes JSON-LD-Array von Events. Senden Sie Content-Type: application/ld+json.

POST/api/v1/epcis/capture
OpenAPI 3.1 herunterladen
POST/api/v1/epcis/capture

EPCIS-Ereignisse erfassen

Die GS1-EPCIS-2.0-Capture-Schnittstelle. Übermitteln Sie Lieferketten-Ereignisse von Partnern, ERP-Systemen oder Werkstatt-Scannern, und TracePass hängt sie an die passenden Pässe an. Der Request-Body akzeptiert vier Formen: ein vollständiges EPCISDocument, ein EPCISQueryDocument, ein einzelnes nacktes Event oder ein nacktes JSON-LD-Array von Events. Senden Sie Content-Type: application/ld+json.

Jedes Event wird auf strukturelle Gültigkeit geprüft (erforderliche Envelope-Schlüssel, Pflichtfelder des Events, Vorhandensein von epcList), anschließend wird jeder EPC in epcList / quantityList zu einem Pass in Ihrem Workspace aufgelöst. Gültige Events werden gespeichert und der Aufruf liefert 202 Accepted mit einer captureJobId. Die Verarbeitung ist abgeschlossen, bevor die Antwort gesendet wird; der Status 202 folgt der Konvention der EPCIS-2.0-Capture-Schnittstelle. Zählt als ein v1-Schreibvorgang, unabhängig davon, wie viele Events das Dokument trägt.

Das Volumen wird gegen das maxEpcisEventsPerMonth des Tarifs gemessen (1.000 bei Basic bis 10.000.000 bei Pro, 10 bei Free, unbegrenzt bei Enterprise). Wenn ein einzelner Capture-Aufruf das Periodenvolumen über das Limit eines kostenpflichtigen Tarifs heben würde, liefert der Endpoint 402 {"error":"epcis_events_overage_required"} mit ausgefüllten overageBlocks + totalOverageCents — wiederholen Sie denselben Aufruf mit "confirmOverage":true im Body, um die Gebühr pro 1.000-Event-Block anzunehmen. Bei Free liefert dieselbe Überschreitung 402 {"error":"epcis_events_hard_block"} mit Upgrade-CTA; kein Pfad für Überschreitungen. Der Aufruf ist auf zwei Arten idempotent — geben Sie einen Idempotency-Key-Header an, um die gesamte Anfrage wiederholungssicher zu machen, und die Plattform dedupliziert zusätzlich über die EPCIS-eventID jedes Events, sodass ein erneut gesendetes Dokument, das eine frühere Erfassung überschneidet, Events nicht doppelt speichert und den Zähler nicht doppelt belastet.

Header

  • Authorizationerforderlich

    string

    Bearer <token> — entweder ein tp_ API-Schlüssel (Developer → API Keys; am einfachsten, für Server-zu-Server) oder ein OAuth-2.0-Access-Token (Developer → OAuth Apps; für nutzerautorisierte Apps, scoped und widerrufbar). Die Authentication-Seite enthält den vollständigen OAuth-Flow und die Scope-Liste.

    e.g. Bearer tp_REDACTED_xxxxxxxxxxxx

  • Idempotency-Key

    string

    UUID v4 — wiederholtes Senden mit demselben Schlüssel liefert das ursprüngliche Erfassungsergebnis. Unabhängig von der eventID-Deduplizierung pro Event.

Body-Felder

  • bodyerforderlich

    EPCISDocument | EPCISQueryDocument | EPCISEvent | EPCISEvent[]

    JSON-LD-Payload, gesendet mit Content-Type: application/ld+json. Akzeptiert ein vollständiges EPCISDocument, ein EPCISQueryDocument, ein nacktes Event oder ein nacktes Array von Events.

  • confirmOverage

    boolean

    Opt-in-Flag, um die Pro-1.000-Event-Blockgebühr für eine Überschreitung zu akzeptieren, wenn eine Erfassung maxEpcisEventsPerMonth überschreiten würde. Ohne dieses Flag liefert der erste Über-dem-Limit-Aufruf einen 402 mit overageBlocks + totalOverageCents im Body — senden Sie denselben Payload erneut mit confirmOverage:true, um die Gebühr zu bestätigen und fortzufahren. Free hat keinen Überschreitungspfad; die Upgrade-erforderlich-Hardblockade ignoriert dieses Flag.

    e.g. true

Anfrage

curl -sS -X POST https://app.tracepass.eu/api/v1/epcis/capture \
  -H "Authorization: Bearer tp_REDACTED_xxxxxxxxxxxx" \
  -H "Idempotency-Key: 7b4f1e2c-9a3d-4e5b-8c1a-2d3e4f5a6b7c" \
  -H "Content-Type: application/ld+json" \
  -d '{
    "@context": "https://ref.gs1.org/standards/epcis/2.0.0/epcis-context.jsonld",
    "type": "EPCISDocument",
    "schemaVersion": "2.0",
    "creationDate": "2026-05-09T12:00:00.000Z",
    "epcisBody": {
      "eventList": [
        {
          "type": "ObjectEvent",
          "eventID": "ni:///sha-256;9f86d0...?ver=CBV2.0",
          "eventTime": "2026-05-09T11:58:00.000Z",
          "eventTimeZoneOffset": "+02:00",
          "epcList": ["https://id.tracepass.eu/p/01/04012345000016/21/BP-48V-100-000001"],
          "action": "OBSERVE",
          "bizStep": "shipping",
          "bizLocation": { "id": "https://id.tracepass.eu/loc/acme-batteries-de" }
        }
      ]
    }
  }'

Antwort

{
  "captureJobId": "6650c4d5e6f7a8b9c0d1e2f3",
  "status": "success",
  "eventCount": 1,
  "capturedCount": 1,
  "errors": []
}

Verwandte Endpoints