eLot Notice Web API

Introduction #

The Tracking Unit Register (TUR) has been introduced as a central database in the official export certification system to store relevant data around tracking units (e.g. in the fruit industry this means data relevant for pallets).

This TUR concept replaces paper-based evidence to demonstrate compliance with the export conditions, as users can now update and call upon the TUR to provide the required confirmation.

The eLot step has been introduced in the certification process and was included for two main purposes. Firstly, the eLot is a means for tracking unit data to be inserted into the TUR.

Secondly, once the data is received by the TUR, the process of pre-verification can take place to ensure the product has met the requirements (up to that point) to be able to be considered for certification.

The objective is to prevent defective product(s) from entering the supply chain at the start of the supply chain.

This guide discusses the eLot API, which is the web service to submit data directly to the TUR and how to interpret the response received back from this service.

Clients will also be shown how to call for information from the TUR so they can track the status of tracking units. The first sections of this document are concerned with how to register and connect to these services, before going into more detail on each of the API endpoints.

Web API Versions #

There are three versions of the API that are presently available at the time and these are stated below:

  • Old – Soon to be deprecated
  • Stable – Current stable version
  • Beta –Latest Build

All requests are sent with the version of the API, the consumer needs to call through a custom request header as below:

The current version of the API will be displayed on the API’s Swagger page. The swagger page will display the available endpoints depending on the selected version.

When a new version becomes available, notifications will be sent out to all the relevant parties with a changelog of the new changes and features. The Swagger page will be updated accordingly with these new features.

The links to the swagger pages are as follows:

Pre-requisites #

The pre-conditions for a consuming (client) system to be able to use the TUR Web API are as follows:

  • The consuming system must belong or be associated with a registered business in the Central Business Register (https://cbr.ecert.co.za/)
  • A client system calling the TUR system will need to be registered as a client in the User Authentication Service(UAS) and issued a valid client Id and client secret to be able to consume the endpoints (see section 1 below)
  • All request calls to the TUR will be authenticated using a JWT (JSON Web token) bearer token over OAuth 2.0 protocol (see How To Connect section)

How to Request API Access on Central Business Register (CBR) #

 Please refer to the Request API Access user guide.

Once a Client has been registered successfully a ClientId, ClientSecret will be generated.The ClientId and ClientSecret, in turn, will be used by the client to authorize and get a token. With a valid token, the client system can call any API endpoint on the TUR Web API provided all the required parameters are presented.

How to Connect #

Refer to the How to Connect to Web API Document

Testing Web API Endpoints #

To test the TUR Web API endpoints users can use 3rd party tools like Swagger or Postman. These tools will help the users to get a feel of what the endpoint parameters look like as well as view the responses in different formats. Below are screenshots to show how to test using both of the tools:

Swagger #

Available Endpoints #

 eLot (POST) #

This eLot Notice web service must be used to submit tracking unit data to the TUR. Pre-verification of the tracking units takes place and the pre-verification results are returned to the client. A brief description of how the key data elements are provided and how to interpret the response is discussed in the table below.

The decision on when to submit the data depends on the client but must be before PPECB quality inspections. Practically data should be submitted when there is certainty regarding the completeness of the tracking unit composition (i.e. it is unlikely to physically change) and the destination of that product is known. The destination is important because the pre-verification process will run the appropriate rules linked to that intended market. The intended market is communicated using the AgreementCode element – which is linked to the Agreements eCertification standard.

IsTest: Client can also trigger the “IsTest” flag as a means to assess the suitability of that product for a possible market without committing to it. The API will run in the same way and appropriate information provided back in the response, but the tracking unit data or results will not be stored in the TUR. If clients want to select that market based on favourable test results the eLot will have to be re-submitted so that the data is added to the TUR and the pre-verification process can be formally undertaken and the results stored. 

AgreementCode:  The AgreementCode can be included at the header level or the Tracking Unit (TU) level. The AgreementCode is optional at the Tracking Unit level and if it is not passed it uses the same value as the one passed on the header. If the AgreementCode is set on the TU level, then it will override the value passed on the header. Having the AgreementCode at the TU level allows for different  Agreement Codes to be set against tracking units as opposed to one Agreement Code being allocated to the eLot.

Please note: An AgreementCode has to be specified at the header or TU level otherwise the database will throw a validation error as this is a required field in the database.

TrackingUnitID: Please note that for the fruit industry, it has been agreed that the tracking unit identification (i.e. the pallet id) must be in the GS1 format (i.e. SSCC). Tracking Unit identification that does not use this convention will not be successfully pre-verified which will result in the product not being certified. It is expected other sectors will also likely use the GS1 standards.

Reference1: Is provided by the client. This Reference has been reserved for the Consignment Note information in the fruit sector if it is known at eLot stage. This may be useful to track consignment of tracking units later.

Reference2: Is provided by the client. In the eLot API, this is an optional reference the client can provide. Examples might be to flag pallets for other parties in their supply chain.

ExportDate: Is provided as the intended date of export. This is relevant when new phytosanitary rules may apply and the system needs to know when the product will be exported so the correct rules are used for pre-verifying. Practically, the current date can be used or the typical timeframe between packing and departure of the product.

Endpoint URL:    http://qa.tur.ecert.co.za/api/TrackingUnit/eLot

Request Parameters

Parameter NameDescriptionRequired?DataTypeExample
BusinessIDBusiness identification from CBR databaseYesString   4
IndustryReference to which industry this TU is fromYesStringFRUIT
AgreementCodeAgreement code used for the export marketNoStringAGM0014
IsTestWhether or not this is a test callYesBooleanFalse. (Default = true)
TrackingUnitsA list of tracking units (including tracking unit detail) to add/update to the system and pre-verifyYesArray   
TrackingUnitIDTracking Unit Identifiers (GS1 Format – SSCC)YesStringe.g. 660091600071233222
AgreementCodeAgreement code used for the export marketNoStringAGM0014
Reference1Provided by client system e.g. consignment number for trackingNoString 
Reference2Providing by client system e.g. other flags to identify tracking unitNoString 
ExportDateIntended Date of Export  No  DateTime  e.g. 2020-01-31  
WeightWeight of tracking unit  YesDecimal  1800.30  
WeightUnitCodeUnit of Measure (ISO Code – 2)  YesStringKG
NumberOfPackageItemsItem count of packaged items  YesInt  20
TrackingUnitDetailsA list of tracking unit details that are contained on a single tracking unitYesArray
OperatorCodeProduction Unit Code – (PUC) Stringe.g. D1234
OriginLocationOrchard Stringe.g. K12
SPSStatusPhyto Status Field String 
PackOperatorCodePackhouse Code (PHC) Stringe.g. L4352
CommodityCodeCommodity Code (2 Character Code)YesStringe.g. LE (LEMONS)
MarketingIndicationCodeVariety CodeYesStringe.g. EUR (EUREKA)
ClassCategoryProduct class categoryYesStringI or II or P
NumberOfPackagedItemsItem count of packaged items for example cartonsYesInt23
PackageTypeType of packaging (ISO Code – 2)YesStringCT
TrackingUnitLocationCurrent location of tracking unit (Future Purposes)NoString 
TrackingUnitOriginOriginal province the tracking unit was created from (Province Code)YesStringGP
InspectionPointLocation Code where tracking units will be inspectedYesString1024

Response

Property Name
IsSuccessful
eLotKey
Message
Data (array)
– TrackingUnitID
– VerificationKey
– ProcessStatus
– ProcessResult (array)
– RejectionReasons (array)
– TrackingUnitDetails(array)  

This section deals with a basic interpretation of the API response.

eLotKey is a unique TUR system generated reference linked to this API call for this set of tracking units.

Message is an array of information returned as a summary of the information across all the tracking units in this eLot. An example might be identifying the pallet with the “worst” phytosanitary status – flagged as the determining status for the whole group of tracking units.

VerificationKey is a unique system-generated reference for this specific tracking unit for this process.

ProcessStatus is the summary result of the process for this particular tracking unit. The possible status values for each process will be reflected in the eCertification standards, but in most cases will be either “Pending”, “Passed” or “Failed”.

ProcessResult is an array of information per tracking unit reflecting the performance against the underlying export conditions being evaluated. Possible values in this array will depend on the process and the underlying export conditions and will correspond with the eCertification standard for Process Results. Conceptually, this field is intended to replace, or be equivalent to, the existing “PhytoData” information. The pallet is thus obtaining a certain phytosanitary status which then remains with that pallet.

RejectionReasons is an array of reasons why the tracking unit has been found not to meet the underlying export condition requirements. The list of reasons corresponds to the eCertification standard for Rejection Reasons per process per agreement.

Examples of Rejection Reasons in the eLot process: 
  • Variety Non-compliance
  • Marketing Indications Non-compliance
  • FBO PUC registration Non-compliance
  • FBO PHC registration Non-compliance
  • Orchard registration Non-compliance
  • PUC count per pallet Non-compliance
  • FBO not recognized
  • Tracking Unit Identifier Non-compliance

Example eLot Response:

{
   IsSuccessful: true,
   eLotKey: “4BA1986”,
   Message: [“Message1”, “Message2”],
   Data: [{
           TrackingUnitID: “760016510576306003”,
           VerificationKey: “4CA1556”,
           ProcessStatus: “Passed”,
           ProcessResult: “EUA1A1FY”,
           RejectionReasons: []
       }, {
           TrackingUnitID: “860016510576596003”,
           VerificationKey: “5RA1534”,
           ProcessStatus: “Failed”,
           ProcessResult: “0”,
           RejectionReasons: [“FBO PUC registration Non-compliance”]
       }
   ]
}

 Get Tracking Unit Status (GET) #

Get status of Tracking Units for each export process. If the results are required for specific export processes, then the ExportProcess element can be used to specifying the export processes required.

Endpoint URL:  http://qa.tur.ecert.co.za/api/TrackingUnit/GetTrackingUnitStatus

Request Parameters

Parameter NameDescriptionRequired?DataTypeExample
TrackingUnitIDIdentify TU in the Tracking Unit RegisterYesstring[760016510576306003, 860016510576596003]
ExportProcess Nostring[eLot, eCert, eInspect]   eLot = Packhouse Pre-Verification eCert = Preloading Check eInspect = Packhouse Phytosanitary Inspection

Response

Property Name
TrackingUnitID 
Industry 
BusinessID 
AgreementCode 
Weight 
WeightUnitCode 
NumberOfPackageItems 
Reference1 
Reference2 
ExportDate 
RegimeCode 
LoadPort 
VerificationKey 
TrackingUnitStatuses (array)ExportProcess (string)
ProcessStatus (string)
ProcessResult (array)
RejectionReasons (array)
Reference1 (string)
Reference2 (string)
UpdatedDateTime (datetime)
TrackingUnitDetails (array)OperatorCode (string)
OriginLocation (string)
SPSStatus (string)
PackOperatorCode (string)
CommodityCode (string)
MarketingIndicationCode (String)
ClassCategory (string)
NumberOfPackageItems (integer)
PackageType (string)
TrackingUnitLocation (string)
TrackingUnitOrigin (string)
InspectionPoint (string)

Tracking Unit Statuses (POST) #

Get status of Tracking Unit for each export process

Endpoint URL:  http://qa.tur.ecert.co.za/api/TrackingUnit/GetTrackingUnitStatuses

Request Parameters

Parameter NameDescriptionRequired?DataTypeExample
TrackingUnitIDsArray of Tracking Unit IDsYesarray[“12345678989987654321”, “123456789987654322”]
ExportProcess YesstringPhytosanitaryInspection

Response

This endpoint returns an array of the Tracking Units 

Property Name
TrackingUnitID 
Industry 
BusinessID 
AgreementCode 
Weight 
WeightUnitCode 
NumberOfPackageItems 
Reference1 
Reference2 
ExportDate 
RegimeCode 
LoadPort 
VerificationKey 
TrackingUnitStatuses (array)ExportProcess (string)
ProcessStatus (string)
ProcessResult (array)
RejectionReasons (array)
Reference1 (string)
Reference2 (string)
UpdatedDateTime (datetime)
TrackingUnitDetails (array)OperatorCode (string)
OriginLocation (string)
SPSStatus (string)
PackOperatorCode (string)
CommodityCode (string)
MarketingIndicationCode (String)
ClassCategory (string)
NumberOfPackageItems (integer)
PackageType (string)
TrackingUnitLocation (string)
TrackingUnitOrigin (string)
InspectionPoint (string)

Get Tracking Unit by Verification Key (GET) #

Get status of a Tracking Unit by using the returned VerificationKey.

Endpoint URL:  http://qa.tur.ecert.co.za/api/TrackingUnit/GetTrackingUnitByVerificationKey

Request Parameters

Property NameDescriptionRequired?DataTypeExample
VerificationKeyVerification key of the TU in the systemYesstring4CA1556
ExportProcess Noarray[eLot, eCert, eInspect]

Response

Property Name
TrackingUnitID 
Industry 
BusinessID 
AgreementCode 
Weight 
WeightUnitCode 
NumberOfPackageItems 
Reference1 
Reference2 
ExportDate 
RegimeCode 
LoadPort 
VerificationKey 
TrackingUnitStatuses (array)ExportProcess (string)
ProcessStatus (string)
ProcessResult (array)
RejectionReasons (array)
Reference1 (string)
Reference2 (string)
UpdatedDateTime (datetime)
TrackingUnitDetails (array)OperatorCode (string)
OriginLocation (string)
SPSStatus (string)
PackOperatorCode (string)
CommodityCode (string)
MarketingIndicationCode(String)
ClassCategory (string)
NumberOfPackageItems (integer)
PackageType (string)
TrackingUnitLocation (string)
TrackingUnitOrigin (string)
InspectionPoint (string)

Get Tracking Units By eLot Key (GET) #

Get status of a Tracking Units

Endpoint URL:  http://qa.tur.ecert.co.za/api/TrackingUnit/GetTrackingUnitByeLotKey

Request Parameters

Parameter NameDescriptionRequired?DataTypeExample
eLotKeyeLot key of the tracking units in the systemYesstring4CA1556
ExportProcess Noarray[eLot, eCert, eInspect]

Response

Property Name
TrackingUnitID 
Industry 
BusinessID 
AgreementCode 
Weight 
WeightUnitCode 
NumberOfPackageItems 
Reference1 
Reference2 
ExportDate 
RegimeCode 
LoadPort 
VerificationKey 
TrackingUnitStatuses (array)ExportProcess (string)
ProcessStatus (string)
ProcessResult (array)
RejectionReasons (array)
Reference1 (string)
Reference2 (string)
UpdatedDateTime (datetime)
TrackingUnitDetails (array)OperatorCode (string)
OriginLocation (string)
SPSStatus (string)
PackOperatorCode (string)
CommodityCode (string)
MarketingIndicationCode(String)
ClassCategory (string)
NumberOfPackageItems (integer)
PackageType (string)
TrackingUnitLocation (string)
TrackingUnitOrigin (string)
InspectionPoint(string)

Add Inspection Result (POST) #

This endpoint is relevant for official inspection bodies that can provide feedback on the inspection status of tracking units. For example, this endpoint is intended to be used by PPECB to submit PHC Quality inspection results. Permissions will apply to ensure that only the correct institutions are adding or updating inspection results.

Endpoint URL:  http://qa.tur.ecert.co.za/api/TrackingUnit/AddInspectionResult

Request Parameters

Parameter NameDescriptionRequired?Data TypeExample
InspectionsCompose of a list of results for each tracking unitYesArray 
TrackingUnitIDIdentify TU in the Tracking Unit RegisterYesstring860016510576596003
IndustryReference to which industry this TU is fromYesstringFRUIT
ExportProcessWhat process the tracking unit is being involved inYesstringeCert
 AgreementCode The market for which tracking unit is  intended should match the TUR value YesstringAGM0001
ProcessStatusAn indication of the status for the AgreementYesstringPassed
ProcessResultThe outcome of the processYesstring80
RejectionReasonsThe reason the process failedYesarrayInappropriate Cartons
BusinessIDBusiness identification from CBR databaseYesstring4
Reference1Client Reference 1NostringXYZ123
Reference2Client Reference 2NostringCL1234

Response

Property Name
IsSuccessful
Message

Update Inspection Result (POST) #

This endpoint is relevant for official inspection bodies that can provide feedback on the inspection status of tracking units. For example, this endpoint is intended to be used by PPECB to submit PHC Quality inspection results. Permissions will apply to ensure that only the correct institutions are adding or updating inspection results.

Endpoint URL:  http://qa.tur.ecert.co.za/api/TrackingUnit/UpdateInspectionResult

Request Parameters

Parameter NameDescriptionRequired?Data TypeExample
InspectionsCompose of a list of results for each tracking unitYesArray 
TrackingUnitIDIdentify TU in the Tracking Unit RegisterYesstring860016510576596003
IndustryReference to which industry this TU is fromYesstringFRUIT
ExportProcessWhat process the tracking unit is being involved inYesstringeCert
AgreementCode The market for which tracking unit is intended should match the TUR value YesstringAGM0001
ProcessStatusAn indication of the status for the AgreementYesstringPassed
ProcessResultThe outcome of the processYesstring80
RejectionReasonsThe reason the process failedYesarrayInappropriate Cartons
BusinessIDBusiness identification from CBR databaseYesstring4
Reference1Client Reference 1NostringXYZ123
Reference2Client Reference 2NostringCL1234

Response

Property Name
IsSuccessful
Message

Tracking Unit (GET) #

Get tracking unit

Endpoint URL:  http://qa.tur.ecert.co.za/api/TrackingUnit/GetTrackingUnit

Request Parameters

Parameter NameDescriptionRequired?DataTypeExample
TrackingUnitID Yesstring12345678989987654321

Response

Property Name
TrackingUnitID 
Reference1 
Reference2 
ExportDate 
Weight 
WeightUnitCode 
NumberOfPackageItems 
TrackingUnitDetails (array)OperatorCode (string)
OriginLocation (string)
SPSStatus (string)
PackOperatorCode (string)
CommodityCode (string)
MarketingIndicationCode (String)
ClassCategory (string)
NumberOfPackageItems (integer)
PackageType (string)
TrackingUnitLocation (string)
TrackingUnitOrigin (string)
InspectionPoint (string)