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 gegen das EPCIS-2.0-Schema validiert, 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 Erfassung ist gemäß dem EPCIS-2.0-Capture-Modell asynchron, fragen Sie also den Job ab (siehe `capture-job`), um das Endergebnis zu erhalten. 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 <api-key>`.

  • 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/04012345000015/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