--- title: Acquisire eventi EPCIS description: Endpoint di acquisizione GS1 EPCIS 2.0. Inviare ObjectEvent / TransformationEvent / AggregationEvent via application/ld+json. Restituisce un capture-job id. canonical: "https://www.tracepass.eu/it/docs/capture-events" locale: it source: "https://www.tracepass.eu/it/docs/capture-events" --- # Acquisire eventi EPCIS > Endpoint di acquisizione GS1 EPCIS 2.0. Inviare ObjectEvent / TransformationEvent / AggregationEvent via application/ld+json. Restituisce un capture-job id. ```http POST /api/v1/epcis/capture ``` 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. ## Parameters | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `Authorization` | header | string | yes | `Bearer ` — 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. | | `Idempotency-Key` | header | string | no | UUID v4 — riproporre la stessa chiave restituisce il risultato di acquisizione originale. Indipendente dalla deduplicazione per `eventID` di ogni evento. | | `body` | body | EPCISDocument \| EPCISQueryDocument \| EPCISEvent \| EPCISEvent\[\] | yes | 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` | body | boolean | no | 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. | ## Examples ```bash 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" } } ] } }' ``` ```typescript import { randomUUID } from "node:crypto"; const epcisDocument = { "@context": "https://ref.gs1.org/standards/epcis/2.0.0/epcis-context.jsonld", type: "EPCISDocument", schemaVersion: "2.0", creationDate: new Date().toISOString(), 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" }, }, ], }, }; const res = await fetch("https://app.tracepass.eu/api/v1/epcis/capture", { method: "POST", headers: { Authorization: `Bearer ${process.env.TRACEPASS_API_KEY}`, "Idempotency-Key": randomUUID(), "Content-Type": "application/ld+json", }, body: JSON.stringify(epcisDocument), }); if (res.status !== 202) throw new Error(`Capture failed: ${res.status}`); const { captureJobId } = await res.json(); // poll capture-job next ``` ```python import os, uuid, requests epcis_document = { "@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"}, } ] }, } res = requests.post( "https://app.tracepass.eu/api/v1/epcis/capture", headers={ "Authorization": f"Bearer {os.environ['TRACEPASS_API_KEY']}", "Idempotency-Key": str(uuid.uuid4()), "Content-Type": "application/ld+json", }, json=epcis_document, ) res.raise_for_status() capture_job_id = res.json()["captureJobId"] # poll capture-job next ``` ## Responses ### 202 — Accettato ```json { "captureJobId": "6650c4d5e6f7a8b9c0d1e2f3", "status": "success", "eventCount": 1, "capturedCount": 1, "errors": [] } ``` ### 401 — Chiave API mancante ```json { "error": "Missing or invalid API key" } ``` ### 402 — Abbonamento richiesto ```json { "error": "Active paid subscription required" } ``` ### 403 — Add-on non attivo ```json { "error": "epcis_capture_not_available" } ``` ## Related - [Interrogare un job di acquisizione](https://www.tracepass.eu/it/docs/capture-job.md) - [Interrogare eventi EPCIS](https://www.tracepass.eu/it/docs/query-events.md)