Receiving from a non-EPCIS Compliant Partner

EPCIS Integration Overview

Our EPCIS integration supports two core functions: Capture and Simple Event Query. These endpoints facilitate the exchange of EPCIS formatted data between two EPCIS compliant solutions, ensuring that shipment and other event data can be sent and received efficiently.

Note: This page assumes that the reader has knowledge and understands how to structure event data according to the EPCIS standard

EPCIS Capture Endpoint

This endpoint is used to capture and send data to and from an EPCIS-compliant system to our platform. We support both XML and JSON-LD formats for submitting event data.

Example Use Case:

Note: This endpoint is specifically designed to work with EPCIS complient traceability platforms

Production Endpoint

POST https://connect.wholechain.com/epcis/Capture

Sandbox Endpoint

POST https://connect-sandbox.wholechain.com/epcis/Capture

Overview

The EPCIS Event Capture API allows users to submit XML-based and JSON-LD-based EPCIS event data. This API is used for capturing various supply chain events, such as observation, shipment, and certification, providing complete traceability for items across the supply chain. It is intended for users who need to submit detailed EPCIS-compliant event data using either XML or JSON-LD format.

This API supports capturing events for:

• Observation Events
• Shipment Events
• Certification and transaction details

Limitations

• Payloads must follow the EPCIS format, including all required namespaces when using XML, or JSON-LD format if applicable.
• The user is assumed to have knowlege of the EPCIS format
• The user is responsible for ensuring that all necessary event attributes (e.g., eventTime, bizStep, and bizLocation) are correctly included.
• Transactions, quantities, and additional trade item information must be formatted in accordance with EPCIS standards.

Authentication

This API uses an API key (X-API-KEY) for authentication. API keys are associated with either an entire account or a specific trade partner in an account. For more information on how to retrieve your API key, refer to the Authentication page.

Request Body Parameters

This API accepts an XML payload that adheres to the EPCIS standard. Below is a breakdown of the key elements and attributes used in this example:

• EPCISQueryDocument: The root element, containing headers, body, and vocabulary data.
• EPCISHeader: Contains metadata such as sender and receiver information.
• EPCISBody: Contains the event details like observation, shipping, and transaction data.

<epcisq:EPCISQueryDocument>
    <EPCISHeader>
        <!-- Standard Business Document Header Info -->
    </EPCISHeader>
    <EPCISBody>
        <epcisq:QueryResults>
            <!-- Event Data -->
        </epcisq:QueryResults>
    </EPCISBody>
</epcisq:EPCISQueryDocument>

{
"@context": "https://www.w3.org/ns/epcis-context.jsonld",
"id": "https://example.org/events/123",
"type": "EPCISEvent",
"eventTime": "2024-09-04T04:16:48Z",
"bizStep": "shipping",
"bizLocation": "urn:epc:id:sgln:0614141.00777.0",
"epcList": [
    "urn:epc:id:sgtin:0614141.107346.2022"
]
}

Request Headers

Example Requests

url = "https://connect.wholechain.com/epcis/Capture"

payload = """
<epcisq:EPCISQueryDocument>
    <EPCISHeader>
        <!-- Standard Business Document Header Info -->
    </EPCISHeader>
    <EPCISBody>
        <epcisq:QueryResults>
            <!-- Event Data -->
        </epcisq:QueryResults>
    </EPCISBody>
</epcisq:EPCISQueryDocument>
"""

headers = {
    "Content-Type": "application/xml",
    "User-Agent": "insomnia/10.0.0",
    "X-API-KEY": "dd581bc3-cf84-4256-abc2-e6c88ac1ed2e"
}

response = requests.post(url, data=payload, headers=headers)

print(response.text)

sh curl -X POST "https://connect.wholechain.com/epcis/Capture" \ -H "Content-Type: application/xml" \ -H "User-Agent: insomnia/10.0.0" \ -H "X-API-KEY: dd581bc3-cf84-4256-abc2-e6c88ac1ed2e" \ --data-raw '<epcisq:EPCISQueryDocument> <EPCISHeader> <!-- Standard Business Document Header Info --> </EPCISHeader> <EPCISBody> <epcisq:QueryResults> <!-- Event Data --> </epcisq:QueryResults> </EPCISBody> </epcisq:EPCISQueryDocument>' 

Example Response

{
    "status": "Success",
    "message": "Event captured successfully",
    "eventId": "urn:uuid:5538b6e9-2fca-45b8-bbb9-cd3855408a4d"
}