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. EQ_bizStep, EQ_disposition e MATCH_epc accettano valori separati da | per corrispondere a una fra più alternative (EQ_bizStep=shipping|receiving); gli altri parametri accettano un solo valore. La corrispondenza è esatta rispetto al valore nella forma in cui è stato acquisito: un evento acquisito con la forma breve shipping non viene trovato con la forma URI CBV, e viceversa. 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. EQ_bizStep, EQ_disposition e MATCH_epc accettano valori separati da | per corrispondere a una fra più alternative (EQ_bizStep=shipping|receiving); gli altri parametri accettano un solo valore. La corrispondenza è esatta rispetto al valore nella forma in cui è stato acquisito: un evento acquisito con la forma breve shipping non viene trovato con la forma URI CBV, e viceversa. 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, Free compreso. Il percorso 403 epcis_query_not_available è raggiungibile solo su spazi di lavoro in cui l'assistenza ha disattivato EPCIS. L'interrogazione è una lettura, quindi continua a funzionare anche quando i pagamenti sono scaduti, non pagati o l'abbonamento è annullato. Le interrogazioni EPCIS vengono attivate su richiesta; finché non sono attive, l'endpoint restituisce 503 {"error":"epcis_query_node_unavailable"} — contattate l'assistenza per attivarle.

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); separate più valori con | per corrispondere a uno qualsiasi di essi. TracePass analizza il parametro e lo applica all'archivio eventi del vostro spazio di lavoro — un valore vuoto o un parametro non supportato restituisce 400.

  • 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. Un valore che non può essere interpretato come data restituisce 400.

  • 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); separate più EPC con | per corrispondere a uno qualsiasi di essi.

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