--- title: Заснемане на EPCIS събития description: GS1 EPCIS 2.0 capture endpoint. Изпращайте ObjectEvent / TransformationEvent / AggregationEvent чрез application/ld+json. Връща capture-job id. canonical: "https://www.tracepass.eu/bg/docs/capture-events" locale: bg source: "https://www.tracepass.eu/bg/docs/capture-events" --- # Заснемане на EPCIS събития > GS1 EPCIS 2.0 capture endpoint. Изпращайте ObjectEvent / TransformationEvent / AggregationEvent чрез application/ld+json. Връща capture-job id. ```http POST /api/v1/epcis/capture ``` GS1 EPCIS 2.0 Capture интерфейсът. Изпращайте събития от веригата на доставки от партньори, ERP системи или скенери в цеха и TracePass ги прикача към съответните паспорти. Тялото на заявката приема четири форми: пълен `EPCISDocument`, `EPCISQueryDocument`, едно самостоятелно събитие или самостоятелен JSON-LD масив от събития. Изпращайте `Content-Type: application/ld+json`. Всяко събитие се валидира спрямо EPCIS 2.0 схемата, след което всеки EPC в `epcList` / `quantityList` се съпоставя с паспорт във вашето работно пространство. Валидните събития се съхраняват и повикването връща `202 Accepted` с `captureJobId` — заснемането е асинхронно според модела за заснемане на EPCIS 2.0, затова заявявайте задачата (вижте `capture-job`) за крайния резултат. Брои се като едно v1 записване независимо колко събития носи документът. Обемът се измерва спрямо `maxEpcisEventsPerMonth` на плана (1 000 при Basic до 10 000 000 при Pro, 10 при Free, неограничено при Enterprise). Когато едно повикване би довело до надхвърляне на лимита при платен план, endpoint-ът връща `402 {"error":"epcis_events_overage_required"}` с попълнени `overageBlocks` + `totalOverageCents` — повторете същото повикване с `"confirmOverage":true` в тялото, за да приемете таксата за блок от 1 000 събития. При Free същото надхвърляне връща `402 {"error":"epcis_events_hard_block"}` с подкана за upgrade; без път за надхвърляне. Повикването е идемпотентно по два начина — подайте header `Idempotency-Key`, за да направите цялата заявка безопасна за повторение, а платформата допълнително дедуплицира по EPCIS `eventID` на всяко събитие, така че повторно изпращане на документ, който се припокрива с предишно заснемане, няма да съхрани събитията двойно и няма да удвои отчета. ## Parameters | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `Authorization` | header | string | yes | `Bearer ` — или `tp_` API ключ (Developer → API Keys; най-просто, за server-to-server), или OAuth 2.0 access token (Developer → OAuth Apps; за приложения, авторизирани от потребител, scoped и отзоваеми). Страницата Authentication съдържа пълния OAuth поток и списъка със scopes. | | `Idempotency-Key` | header | string | no | UUID v4 — повтаряне на същия ключ връща оригиналния резултат от заснемането. Независимо от дедупликацията по `eventID` на всяко събитие. | | `body` | body | EPCISDocument \| EPCISQueryDocument \| EPCISEvent \| EPCISEvent\[\] | yes | JSON-LD полезен товар, изпратен с `Content-Type: application/ld+json`. Приема пълен EPCISDocument, EPCISQueryDocument, самостоятелно събитие или самостоятелен масив от събития. | | `confirmOverage` | body | boolean | no | Флаг по избор за приемане на таксата за блок от 1 000 събития, когато заснемането би надхвърлило `maxEpcisEventsPerMonth`. Без него първото повикване над лимита връща 402 с `overageBlocks` + `totalOverageCents` в тялото — изпратете повторно същия полезен товар с `confirmOverage:true`, за да потвърдите таксата и да продължите. Free няма път за надхвърляне; твърдата блокада за upgrade игнорира този флаг. | ## Examples ```bash 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" } } ] } }' ``` ```typescript import { randomUUID } from "node:crypto"; const epcisDocument = { "@context": "https://ref.gs1.org/standards/epcis/2.0.0/epcis-context.jsonld", type: "EPCISDocument", schemaVersion: "2.0", creationDate: new Date().toISOString(), 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" }, }, ], }, }; const res = await fetch("https://app.tracepass.eu/api/v1/epcis/capture", { method: "POST", headers: { Authorization: `Bearer ${process.env.TRACEPASS_API_KEY}`, "Idempotency-Key": randomUUID(), "Content-Type": "application/ld+json", }, body: JSON.stringify(epcisDocument), }); if (res.status !== 202) throw new Error(`Capture failed: ${res.status}`); const { captureJobId } = await res.json(); // poll capture-job next ``` ```python import os, uuid, requests epcis_document = { "@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"}, } ] }, } res = requests.post( "https://app.tracepass.eu/api/v1/epcis/capture", headers={ "Authorization": f"Bearer {os.environ['TRACEPASS_API_KEY']}", "Idempotency-Key": str(uuid.uuid4()), "Content-Type": "application/ld+json", }, json=epcis_document, ) res.raise_for_status() capture_job_id = res.json()["captureJobId"] # poll capture-job next ``` ## Responses ### 202 — Прието ```json { "captureJobId": "6650c4d5e6f7a8b9c0d1e2f3", "status": "success", "eventCount": 1, "capturedCount": 1, "errors": [] } ``` ### 401 — Липсва API ключ ```json { "error": "Missing or invalid API key" } ``` ### 402 — Изисква се абонамент ```json { "error": "Active paid subscription required" } ``` ### 403 — Add-on не е активиран ```json { "error": "epcis_capture_not_available" } ``` ## Related - [Заявяване на задача за заснемане](https://www.tracepass.eu/bg/docs/capture-job.md) - [Заявяване на EPCIS събития](https://www.tracepass.eu/bg/docs/query-events.md)