Communication Protocol Supplementary Guide
Using the EPICS Capture Interface to Push Traceability Data
Overview
In the GDST’s Standards and Guidelines for Interoperable Seafood Traceability Systems – Technical Implementation Guidance (version 1.2) there are two workflows that are described, the Business-to-Business (B2B) workflow and the Internal System-to-System workflow. The Business-to-Business workflow focuses on where two external parties want to exchange traceability data, typically revolving around a seller and buyer.
The working group that helped to establish the technical standard and workflows decided that:
“For the purpose of this workflow, we will assume that the Receiver (Buyer) has received a list of EPC(s) through another workflow and is now attempting to resolve traceability data and master data for these EPC(s).” – GDST Technical Standard 1.2 – Page 11
However, some solution providers do not have a standardized way to meet this requirement and communicate a list of received EPCs from a seller. This document is meant to provide a way for a seller to communicate a list of EPCs to the buyer, so that the buyer can then use the Business-to-Business workflow to request the traceability data for the products.
Push Communication Protocol
The Push Communication Protocol introduces an optional preliminary step to the Business-to-Business communication protocol that takes advantage of the EPCIS Capture Interface, exposed on the EPCIS 2.0 REST API (“/capture”) endpoint. This endpoint would be allowed for a seller (sender) to send a single shipping event to the buyer (receiver) to act as an Advanced Shipment Notification (ASN).
EPCIS Capture Interface
The EPCIS Capture Interface allows for one or more events to be pushed to an EPCIS server. While this interface was originally designed around an internal application that is recording events as they occur in real time, it is possible to use the interface to also push an event from a seller to a buyer.
EPCIS 2.0 Standard – 8.1.2 – Capture Service
The EPCIS 2.0 OpenAPI definition for the REST Capture Interface is defined as:
This visual was generated using Swagger.io and the original source for this visual of the OpenAPI definition can be found at https://ref.gs1.org/standards/epcis/openapi.json.
The Push Protocol
The push protocol would follow these steps:
- Seller pushes a shipping event to the buyer’s EPCIS Capture Interface. This shipping event would follow the same GDST shipping event requirements. It would contain a list of all EPCs that the seller wants the buyer to be aware of so that the buyer can request the traceability data for these EPCs.
- This will be done using the “/capture” endpoint on the EPCIS REST Interface exposed by the buyer.
- The HTTP header “GS1-EPCIS-Version” would be set to “2.0” and the data format would be JSON-LD.
- Buyer uses the list of EPCs in the shipping event to pull the remaining traceability and master data from the seller using the GDST Communication B2B Workflow as defined in the GDST Technical 1.2 Standard.
Technical Details
Some technical details to consider:
- The /capture endpoint should receive only an EPCIS Query Document per this push protocol.
- The EPCIS 2.0 standard as a whole does allow both the EPCIS Document and the EPCIS Query Document, however, this push protocol restricts this to just an EPCIS Query Document. Master data must be resolved through digital link.
- The “/capture” end point is designed to be an asynchronous job, meaning that the actual processing of the received data can be done asynchronously.
- The response header should contain a relative URL such as “/capture/id9261379075” that can be used to monitor the asynchronous job to ensure that it was completed successfully.
- The X-API-Key header is still the recommended way to enable authentication and should be provided on the request header to the “/capture” endpoint.
Security Considerations
Some security considerations:
- An API Key should be assigned for each seller/buyer relationship and each buyer/seller relationship such that a buyer will assign a unique API Key to each seller that will query their API, and a seller will assign a unique API Key to each buyer that will query their API.
- If the “/capture” endpoint detects an API Key is used, it should ensure that only a single shipping event is contained in the posted EPCIS events, and that the shipping event has a buyer and seller where the seller matches who the API Key was assigned to and the buyer matches the owner of the API.
- This security consideration may need flexibility in the case where a 3rd party is in between the seller and buyer.
- If possible, the allowed GTINs in the EPC list should be restricted such that for specific seller (API Key), it will return an error if a EPC listed contains a GTIN that is not allowed.
- If possible, the EPCs contained in the pushed shipping event should be corroborated with a purchase order.
- The shipping event could include the Purchase Order Number in the Business Transaction section of the event.
