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.

Всяко събитие се проверява за структурна валидност (задължителни envelope ключове, задължителни полета на събитието, наличие на epcList), след което всеки EPC в epcList / quantityList се съпоставя с паспорт във вашето работно пространство. Валидните събития се съхраняват и повикването връща 202 Accepted с captureJobId. Обработката приключва преди изпращането на отговора; статус 202 отразява конвенцията на EPCIS 2.0 capture интерфейса. Брои се като едно 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 <token> — или tp_ API ключ (Developer → API Keys; най-просто, за server-to-server), или OAuth 2.0 access token (Developer → OAuth Apps; за приложения, авторизирани от потребител, scoped и отзоваеми). Страницата Authentication съдържа пълния OAuth поток и списъка със scopes.

    e.g. Bearer tp_REDACTED_xxxxxxxxxxxx

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