---
title: EPCIS-Ereignisse abfragen
description: GS1-EPCIS-2.0-Query-Endpoint. Erfasste Events via EQ_bizStep / GE_eventTime / MATCH_epc und der EPCIS-Query-Grammatik durchsuchen. Liefert EPCISQueryDocument.
canonical: "https://www.tracepass.eu/de/docs/query-events"
locale: de
source: "https://www.tracepass.eu/de/docs/query-events"
---

# EPCIS-Ereignisse abfragen

> GS1-EPCIS-2.0-Query-Endpoint. Erfasste Events via EQ_bizStep / GE_eventTime / MATCH_epc und der EPCIS-Query-Grammatik durchsuchen. Liefert EPCISQueryDocument.

```http
GET /api/v1/epcis/events
```

Die GS1-EPCIS-2.0-Query-Schnittstelle. Durchsuchen Sie erfasste Lieferketten-Ereignisse mit der Standard-EPCIS-Query-Parameter-Grammatik — `EQ_bizStep`, `GE_eventTime`, `LT_eventTime`, `MATCH_epc`, `EQ_bizLocation` und dem Rest der `EQ_*`- / `GE_*`- / `LT_*`- / `MATCH_*`-Familie. Parameter werden wortgetreu an die EPCIS-Query-Schnittstelle durchgereicht, sodass jede von der GS1-Grammatik erlaubte Abfrage hier unverändert funktioniert.

TracePass leitet die Abfrage an einen OpenEPCIS-Query-Knoten weiter und liefert das Ergebnis als standardkonformes `EPCISQueryDocument` (`Content-Type: application/ld+json`). Zählt als ein Lesevorgang.

Tarif-Gate: EPCIS-Abfragen sind in jedem kostenpflichtigen Tarif enthalten (und auf Free gegen einen leeren Index — nützlich für die Integrationsvalidierung). Der 403-`epcis_query_not_available`-Pfad ist nur auf Workspaces erreichbar, deren `epcisCaptureEnabled`-Flag per Tenant-Override deaktiviert wurde. Ein abgelaufenes Abonnement liefert `402`. Der Query-Knoten wird auf Anfrage statt standardmäßig bereitgestellt — bis er für Ihren Workspace ausgerollt ist, liefert der Endpoint `503 {"error":"epcis_query_node_unavailable"}`; wenden Sie sich an den Support, damit er eingerichtet wird.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Authorization` | header | string | yes | `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. |
| `EQ_bizStep` | query | string | no | Standard-EPCIS-Query-Parameter — matcht Events, deren `bizStep` dem angegebenen CBV-Wert entspricht (z. B. `shipping`, `receiving`). Wird wortgetreu an die EPCIS-Query-Schnittstelle durchgereicht. |
| `GE_eventTime` | query | string (ISO 8601) | no | Standard-EPCIS-Query-Parameter — matcht Events, deren `eventTime` größer oder gleich dem angegebenen Zeitstempel ist. Mit `LT_eventTime` für ein Zeitfenster kombinieren. Wird wortgetreu durchgereicht. |
| `MATCH_epc` | query | string | no | Standard-EPCIS-Query-Parameter — matcht Events, deren `epcList` den angegebenen EPC enthält (eine TracePass-Pass-Digital-Link-URI). Wird wortgetreu durchgereicht. |

## Examples

```bash
# All shipping events for one passport in a time window
curl -sS -G https://app.tracepass.eu/api/v1/epcis/events \
  -H "Authorization: Bearer tp_REDACTED_xxxxxxxxxxxx" \
  --data-urlencode "EQ_bizStep=shipping" \
  --data-urlencode "GE_eventTime=2026-01-01T00:00:00.000Z" \
  --data-urlencode "LT_eventTime=2026-06-01T00:00:00.000Z" \
  --data-urlencode "MATCH_epc=https://id.tracepass.eu/p/01/04012345000016/21/BP-48V-100-000001"
```

```typescript
const url = new URL("https://app.tracepass.eu/api/v1/epcis/events");
url.searchParams.set("EQ_bizStep", "shipping");
url.searchParams.set("GE_eventTime", "2026-01-01T00:00:00.000Z");
url.searchParams.set("LT_eventTime", "2026-06-01T00:00:00.000Z");
url.searchParams.set(
  "MATCH_epc",
  "https://id.tracepass.eu/p/01/04012345000016/21/BP-48V-100-000001",
);

const res = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.TRACEPASS_API_KEY}` },
});
if (res.status === 503) throw new Error("Query node not provisioned");
const queryDocument = await res.json(); // EPCISQueryDocument
```

```python
import os, requests

res = requests.get(
    "https://app.tracepass.eu/api/v1/epcis/events",
    headers={"Authorization": f"Bearer {os.environ['TRACEPASS_API_KEY']}"},
    params={
        "EQ_bizStep": "shipping",
        "GE_eventTime": "2026-01-01T00:00:00.000Z",
        "LT_eventTime": "2026-06-01T00:00:00.000Z",
        "MATCH_epc": "https://id.tracepass.eu/p/01/04012345000016/21/BP-48V-100-000001",
    },
)
res.raise_for_status()
query_document = res.json()  # EPCISQueryDocument
```

## Responses

### 200 — OK

```json
{
  "@context": "https://ref.gs1.org/standards/epcis/2.0.0/epcis-context.jsonld",
  "type": "EPCISQueryDocument",
  "schemaVersion": "2.0",
  "creationDate": "2026-05-09T12:00:00.000Z",
  "epcisBody": {
    "queryResults": {
      "resultsBody": {
        "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"
          }
        ]
      }
    }
  }
}
```

### 401 — API-Schlüssel fehlt

```json
{ "error": "Missing or invalid API key" }
```

### 402 — Abonnement erforderlich

```json
{ "error": "Active paid subscription required" }
```

### 403 — Add-on nicht aktiviert

```json
{ "error": "epcis_query_not_available" }
```

### 503 — Query-Knoten nicht verfügbar

```json
{ "error": "epcis_query_node_unavailable" }
```

## Related

- [EPCIS-Ereignisse erfassen](https://www.tracepass.eu/de/docs/capture-events.md)
- [EPCIS-Ereignisse eines Passes exportieren](https://www.tracepass.eu/de/docs/passport-epcis-export.md)