Skip to main content

EPCIS Capture

The EPCIS Capture endpoint allows you to submit supply chain event data to TrackVision using the GS1 EPCIS 2.0 compliant capture interface. It is the only way to submit EPCIS events into the system.

Supported Event Types​

The capture endpoint supports all EPCIS 2.0 event types:

  • ObjectEvent - Events that capture information about physical objects
  • AggregationEvent - Events that describe the aggregation/disaggregation of objects
  • TransactionEvent - Events that associate objects with business transactions
  • TransformationEvent - Events that describe the transformation of objects
  • AssociationEvent - Events that describe the association/disassociation of objects

Endpoints​

Capture Endpoint​

POST https://epcis.yourdomain.trackvision.ai/v2/epcis/capture

Validate Endpoint​

POST https://epcis.yourdomain.trackvision.ai/v2/epcis/validate

Replace yourdomain with your actual TrackVision subdomain.

The validate endpoint allows you to validate the compliance of your EPCIS message with the EPCIS 2.0 schema without committing any data to the system. This is useful for testing and validation during development.

JSON Schema Validation Tool

JSON Schema Validator is a great online tool for visualizing where in your messages you have specific errors. You can paste your EPCIS JSON document and the validation errors to better understand the structure and location of issues.

You can use the official EPCIS 2.0 JSON Schema for validation.

Request Format​

The capture endpoint accepts EPCIS events in JSON-LD format according to the GS1 EPCIS 2.0 specification.

Headers​

Content-Type: application/json
Authorization: Bearer <your-token>

Request Body​

The request body should contain an EPCIS document with one or more events:

{
  "@context": [
    "https://ref.gs1.org/standards/epcis/2.0.0/epcis-context.jsonld"
  ],
  "type": "EPCISDocument",
  "schemaVersion": "2.0",
  "creationDate": "2024-01-15T10:30:00.000Z",
  "epcisBody": {
    "eventList": [
      {
        "type": "ObjectEvent",
        "eventTime": "2024-01-15T10:30:00.000Z",
        "eventTimeZoneOffset": "+00:00",
        "epcList": [
          "urn:epc:id:sgtin:0614141.812345.6789"
        ],
        "action": "OBSERVE",
        "bizStep": "shipping",
        "readPoint": {
          "id": "urn:epc:id:sgln:0614141.00777.0"
        }
      }
    ]
  }
}

Response​

Capture Endpoint - Success Response​

HTTP/1.1 201 Created
Content-Type: application/json

{
  "type": "EPCISCaptureResponse",
  "captureID": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Events captured successfully"
}

Capture Endpoint - Error Response​

HTTP/1.1 400 Bad Request
Content-Type: text/plain

EPCIS Document is invalid;
(root): Must validate "then" as "if" was valid;
epcisBody.eventList.0: Must validate "then" as "if" was valid;
epcisBody.eventList.0.readPoint.id: Does not match format 'uri';
epcisBody.eventList.0: Must validate all the schemas (allOf);
epcisBody.eventList.0: Must validate all the schemas (allOf);
(root): Must validate all the schemas (allOf)

Validate Endpoint - Success Response​

HTTP/1.1 200 OK
Content-Type: application/json

{
  "type": "EPCISValidationResponse",
  "status": "valid",
  "message": "EPCIS document is valid and compliant with EPCIS 2.0 schema"
}

Validate Endpoint - Error Response​

HTTP/1.1 400 Bad Request
Content-Type: text/plain

EPCIS Document is invalid;
(root): Must validate "then" as "if" was valid;
epcisBody.eventList.0: Must validate "then" as "if" was valid;
epcisBody.eventList.0.readPoint.id: Does not match format 'uri';
epcisBody.eventList.0: Must validate all the schemas (allOf);
epcisBody.eventList.0: Must validate all the schemas (allOf);
(root): Must validate all the schemas (allOf)

Validation​

All submitted EPCIS data is validated the EPCIS 2.0 schema. The system also generates EventIDs using the hashing algorithm in the CBV, which enforces additional validation of the structure of various GS1 CBV vocabulary elements.

Validation Error Format​

When validation fails, both the capture and validate endpoints return detailed error messages in plain text format, indicating:

  • Schema violations - Fields that don't match expected formats (e.g., invalid URI format)
  • Conditional validation failures - "if/then" schema conditions that aren't met
  • Structural issues - Problems with the overall document structure
  • Field-specific errors - Exact location of problematic data (e.g., epcisBody.eventList.0.readPoint.id)

Best Practices​

Batch Processing​

  • It is possible to submit a large set of events in a single capture request if desired.
  • Alternatively, you can submit a single event per request.

Error Handling​

  • Implement retry logic for transient failures
  • Use the /epcis/validate endpoint to validate EPCIS documents before submission
  • Validate EPCIS documents locally before sending to reduce errors
  • Monitor capture responses for validation errors

Example EPCIS Messages​

The GS1 organization maintains a comprehensive collection of example EPCIS messages in JSON format. These examples demonstrate various event types and use cases:

📁 EPCIS JSON Examples Repository

This repository includes examples for:

  • Simple Events - Basic event structures for each event type
  • With Error Declaration - Events that include error declarations
  • With Sensor Data - Events containing IoT sensor information
  • All Event Types - ObjectEvent, AggregationEvent, TransactionEvent, TransformationEvent, and AssociationEvent

These examples are valuable for:

  • Understanding proper EPCIS 2.0 JSON structure
  • Understanding usage of various attributes and parts of the EPCIS standard
  • Testing your implementation with basic sample data
  • Validating your capture endpoint integration