TracePass
Inizia ora
EPCIS 2.0

Interrogare eventi EPCIS

Cercate gli eventi della catena di approvvigionamento che avete acquisito usando i parametri di query EPCIS 2.0. Ne sono supportati otto: `EQ_bizStep`, `EQ_disposition`, `EQ_eventType`, `MATCH_epc`, `EQ_bizLocation`, `EQ_readPoint`, `GE_eventTime` e `LT_eventTime`. I valori possono essere separati da `|` per corrispondere a una fra più alternative (`EQ_bizStep=shipping|receiving`). Qualsiasi altro parametro restituisce `400` invece di essere ignorato in silenzio: un errore di battitura fallisce in modo visibile anziché allargare i vostri risultati.

GET/api/v1/epcis/events
Scarica OpenAPI 3.1
GET/api/v1/epcis/events

Interrogare eventi EPCIS

Cercate gli eventi della catena di approvvigionamento che avete acquisito usando i parametri di query EPCIS 2.0. Ne sono supportati otto: `EQ_bizStep`, `EQ_disposition`, `EQ_eventType`, `MATCH_epc`, `EQ_bizLocation`, `EQ_readPoint`, `GE_eventTime` e `LT_eventTime`. I valori possono essere separati da `|` per corrispondere a una fra più alternative (`EQ_bizStep=shipping|receiving`). Qualsiasi altro parametro restituisce `400` invece di essere ignorato in silenzio: un errore di battitura fallisce in modo visibile anziché allargare i vostri risultati.

I risultati tornano come `EPCISQueryDocument` valido secondo lo standard (`Content-Type: application/ld+json`), dal più recente, e includono solo eventi acquisiti e approvati dal vostro spazio di lavoro. Una risposta si ferma a 1000 eventi; se ve n'erano di più viene impostato `X-TracePass-Result-Truncated: true` — restringete l'intervallo con `GE_eventTime` / `LT_eventTime` per scorrere le pagine. Conta come una lettura.

Gate del piano: le interrogazioni EPCIS sono incluse in ogni piano a pagamento (e su Free contro un indice vuoto — utile per la validazione dell'integrazione). Il percorso 403 `epcis_query_not_available` è raggiungibile solo su spazi di lavoro il cui flag `epcisCaptureEnabled` è stato disabilitato tramite override per tenant. Un abbonamento scaduto restituisce `402`. Il nodo di interrogazione viene fornito su richiesta anziché per impostazione predefinita — finché non è distribuito per il vostro spazio di lavoro l'endpoint restituisce `503 {"error":"epcis_query_node_unavailable"}`; contattate l'assistenza per farlo attivare.

Parametri di query

  • EQ_bizStep

    string

    Parametro di query EPCIS standard — corrisponde agli eventi il cui `bizStep` è uguale al valore CBV indicato (es. `shipping`, `receiving`). Passato verbatim all'interfaccia di interrogazione EPCIS.

  • GE_eventTime

    string (ISO 8601)

    Parametro di query EPCIS standard — corrisponde agli eventi il cui `eventTime` è maggiore o uguale al timestamp indicato. Abbinatelo a `LT_eventTime` per una finestra. Passato verbatim.

  • MATCH_epc

    string

    Parametro di query EPCIS standard — corrisponde agli eventi il cui `epcList` contiene l'EPC indicato (un URI Digital Link di un passaporto TracePass). Passato verbatim.

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

Richiesta

# All shipping events for one passport in a time window
curl -sS -G https://app.tracepass.eu/api/v1/epcis/events \
  -H "Authorization: Bearer tp_REDACTED_xxxxxxxxxxxx" \
  --data-urlencode "EQ_bizStep=shipping" \
  --data-urlencode "GE_eventTime=2026-01-01T00:00:00.000Z" \
  --data-urlencode "LT_eventTime=2026-06-01T00:00:00.000Z" \
  --data-urlencode "MATCH_epc=https://id.tracepass.eu/p/01/04012345000016/21/BP-48V-100-000001"

Risposta

{
  "@context": "https://ref.gs1.org/standards/epcis/2.0.0/epcis-context.jsonld",
  "type": "EPCISQueryDocument",
  "schemaVersion": "2.0",
  "creationDate": "2026-05-09T12:00:00.000Z",
  "epcisBody": {
    "queryResults": {
      "resultsBody": {
        "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"
          }
        ]
      }
    }
  }
}

Endpoint correlati