TracePass
Започнете
EPCIS 2.0

Заснемане на EPCIS събития

GS1 EPCIS 2.0 Capture интерфейсът. Изпращайте събития от веригата на доставки от партньори, ERP системи или скенери в цеха и TracePass ги прикача към съответните паспорти. Тялото на заявката приема четири форми: пълен `EPCISDocument`, `EPCISQueryDocument`, едно самостоятелно събитие или самостоятелен JSON-LD масив от събития. Изпращайте `Content-Type: application/ld+json`.

POST/api/v1/epcis/capture
Изтегли OpenAPI 3.1
POST/api/v1/epcis/capture

Заснемане на EPCIS събития

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` на всяко събитие, така че повторно изпращане на документ, който се припокрива с предишно заснемане, няма да съхрани събитията двойно и няма да удвои отчета.

Хедъри

  • Authorizationзадължително

    string

    `Bearer <api-key>`.

  • Idempotency-Key

    string

    UUID v4 — повтаряне на същия ключ връща оригиналния резултат от заснемането. Независимо от дедупликацията по `eventID` на всяко събитие.

Полета в тялото

  • bodyзадължително

    EPCISDocument | EPCISQueryDocument | EPCISEvent | EPCISEvent[]

    JSON-LD полезен товар, изпратен с `Content-Type: application/ld+json`. Приема пълен EPCISDocument, EPCISQueryDocument, самостоятелно събитие или самостоятелен масив от събития.

  • confirmOverage

    boolean

    Флаг по избор за приемане на таксата за блок от 1 000 събития, когато заснемането би надхвърлило `maxEpcisEventsPerMonth`. Без него първото повикване над лимита връща 402 с `overageBlocks` + `totalOverageCents` в тялото — изпратете повторно същия полезен товар с `confirmOverage:true`, за да потвърдите таксата и да продължите. Free няма път за надхвърляне; твърдата блокада за upgrade игнорира този флаг.

    e.g. true

Заявка

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" }
        }
      ]
    }
  }'

Отговор

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

Свързани endpoints