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 sottoposto a un controllo di validità strutturale (chiavi envelope obbligatorie, campi obbligatori dell'evento, presenza di epcList), 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'elaborazione si completa prima che la risposta venga inviata; lo stato 202 riflette la convenzione dell'interfaccia di acquisizione EPCIS 2.0. 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 <token> — una chiave API tp_ (Developer → API Keys; più semplice, per server-to-server) oppure un access token OAuth 2.0 (Developer → OAuth Apps; per app autorizzate dall'utente, scoped e revocabili). La pagina Authentication contiene il flusso OAuth completo e l'elenco degli scopes.

    e.g. Bearer tp_REDACTED_xxxxxxxxxxxx

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