TracePass
Inizia ora
EPCIS 2.0

Acquisire eventi EPCIS

L'interfaccia di acquisizione GS1 EPCIS 2.0. Inviate eventi della catena di approvvigionamento da partner, sistemi ERP o scanner di reparto e TracePass li allega ai passaporti corrispondenti. Il corpo della richiesta accetta quattro forme: un `EPCISDocument` completo, un `EPCISQueryDocument`, un singolo evento nudo o un array JSON-LD nudo di eventi. Inviate `Content-Type: application/ld+json`.

POST/api/v1/epcis/capture
Scarica OpenAPI 3.1
POST/api/v1/epcis/capture

Acquisire eventi EPCIS

L'interfaccia di acquisizione GS1 EPCIS 2.0. Inviate eventi della catena di approvvigionamento da partner, sistemi ERP o scanner di reparto e TracePass li allega ai passaporti corrispondenti. Il corpo della richiesta accetta quattro forme: un `EPCISDocument` completo, un `EPCISQueryDocument`, un singolo evento nudo o un array JSON-LD nudo di eventi. Inviate `Content-Type: application/ld+json`.

Ogni evento viene convalidato rispetto allo schema EPCIS 2.0, quindi ogni EPC in `epcList` / `quantityList` viene risolto a un passaporto nel vostro spazio di lavoro. Gli eventi validi vengono memorizzati e la chiamata restituisce `202 Accepted` con un `captureJobId` — l'acquisizione è asincrona secondo il modello di acquisizione EPCIS 2.0, quindi interrogate il job (vedi `capture-job`) per l'esito finale. Conta come una scrittura v1 indipendentemente da quanti eventi contiene il documento.

Il volume è misurato rispetto al `maxEpcisEventsPerMonth` del piano (1.000 su Basic fino a 10.000.000 su Pro, 10 su Free, illimitato su Enterprise). Quando una singola chiamata di acquisizione porterebbe il totale di periodo oltre il limite su un piano a pagamento, l'endpoint restituisce `402 {"error":"epcis_events_overage_required"}` con `overageBlocks` + `totalOverageCents` popolati — ripetete la stessa chiamata con `"confirmOverage":true` nel corpo per accettare la tariffa per blocco da 1.000 eventi. Su Free lo stesso superamento restituisce `402 {"error":"epcis_events_hard_block"}` con CTA di upgrade; nessun percorso di superamento. La chiamata è idempotente in due modi — fornite un header `Idempotency-Key` per rendere l'intera richiesta sicura per la ripetizione, e la piattaforma deduplica inoltre in base all'`eventID` EPCIS di ogni evento, così reinviare un documento che si sovrappone a un'acquisizione precedente non memorizzerà gli eventi due volte né conterà due volte sul misuratore.

Header

  • Authorizationobbligatorio

    string

    `Bearer <api-key>`.

  • Idempotency-Key

    string

    UUID v4 — riproporre la stessa chiave restituisce il risultato di acquisizione originale. Indipendente dalla deduplicazione per `eventID` di ogni evento.

Campi del corpo

  • bodyobbligatorio

    EPCISDocument | EPCISQueryDocument | EPCISEvent | EPCISEvent[]

    Payload JSON-LD inviato con `Content-Type: application/ld+json`. Accetta un EPCISDocument completo, un EPCISQueryDocument, un evento nudo o un array nudo di eventi.

  • confirmOverage

    boolean

    Flag opt-in per accettare la tariffa di superamento per blocco da 1.000 eventi quando un'acquisizione supererebbe `maxEpcisEventsPerMonth`. Senza di esso, la prima chiamata oltre il limite restituisce 402 con `overageBlocks` + `totalOverageCents` nel corpo — reinviate lo stesso payload con `confirmOverage:true` per riconoscere l'addebito e procedere. Il piano Free non ha percorso di superamento; il blocco rigido di upgrade ignora questo flag.

    e.g. true

Richiesta

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

Risposta

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

Endpoint correlati