---
title: Заявяване на EPCIS събития
description: GS1 EPCIS 2.0 query endpoint. Търсене на събития чрез EQ_bizStep / GE_eventTime / MATCH_epc и стандартната EPCIS query grammar. Връща EPCISQueryDocument.
canonical: "https://www.tracepass.eu/bg/docs/query-events"
locale: bg
source: "https://www.tracepass.eu/bg/docs/query-events"
---

# Заявяване на EPCIS събития

> GS1 EPCIS 2.0 query endpoint. Търсене на събития чрез EQ_bizStep / GE_eventTime / MATCH_epc и стандартната EPCIS query grammar. Връща EPCISQueryDocument.

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

GS1 EPCIS 2.0 Query интерфейсът. Търсете заснети събития от веригата на доставки със стандартната граматика на EPCIS query параметрите — `EQ_bizStep`, `GE_eventTime`, `LT_eventTime`, `MATCH_epc`, `EQ_bizLocation` и останалите от семейството `EQ_*` / `GE_*` / `LT_*` / `MATCH_*`. Параметрите се предават дословно към EPCIS query интерфейса, така че всяка заявка, която граматиката на GS1 позволява, работи тук непроменена.

TracePass пренасочва заявката към OpenEPCIS query възел и връща резултата като валиден според стандарта `EPCISQueryDocument` (`Content-Type: application/ld+json`). Брои се като едно четене.

Гейт на плана: EPCIS заявките са включени във всеки платен план (а на Free — спрямо празен индекс, полезно за валидация на интеграцията). Пътят 403 `epcis_query_not_available` е достъпен само при работни пространства, чийто флаг `epcisCaptureEnabled` е изключен чрез per-tenant override. Изтекъл абонамент връща `402`. Query възелът се осигурява при поискване, а не по подразбиране — докато не бъде разгърнат за вашето работно пространство, endpoint-ът връща `503 {"error":"epcis_query_node_unavailable"}`; свържете се с поддръжката, за да бъде вдигнат.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Authorization` | header | string | yes | `Bearer <token>` — или `tp_` API ключ (Developer → API Keys; най-просто, за server-to-server), или OAuth 2.0 access token (Developer → OAuth Apps; за приложения, авторизирани от потребител, scoped и отзоваеми). Страницата Authentication съдържа пълния OAuth поток и списъка със scopes. |
| `EQ_bizStep` | query | string | no | Стандартен EPCIS query параметър — съответства на събития, чийто `bizStep` е равен на дадената CBV стойност (напр. `shipping`, `receiving`). Предава се дословно към EPCIS query интерфейса. |
| `GE_eventTime` | query | string (ISO 8601) | no | Стандартен EPCIS query параметър — съответства на събития, чийто `eventTime` е по-голям или равен на дадения времеви маркер. Комбинирайте с `LT_eventTime` за прозорец. Предава се дословно. |
| `MATCH_epc` | query | string | no | Стандартен EPCIS query параметър — съответства на събития, чийто `epcList` съдържа дадения EPC (Digital Link URI на паспорт в TracePass). Предава се дословно. |

## 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 ключ

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

### 402 — Изисква се абонамент

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

### 403 — Add-on не е активиран

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

### 503 — Query възелът е недостъпен

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

## Related

- [Заснемане на EPCIS събития](https://www.tracepass.eu/bg/docs/capture-events.md)
- [Експорт на EPCIS събитията на паспорт](https://www.tracepass.eu/bg/docs/passport-epcis-export.md)