ELOT Notice and Trade Unit Register Web API Guide

eLOT Notice and Trade Unit Register Web API Guide

Version 1.0

eLOT Notice and Trade Unit Register Web API Guide

Table of Contents

Version 1.0 ................................................................................................................................................ 1 Introduction .................................................................................................................................................. 3 Web API Versions.......................................................................................................................................... 3 Pre-requisites ................................................................................................................................................ 4

1. How to register Client on User Authentication Service (UAS) .......................................................... 4 2. How to Connect ................................................................................................................................ 4 2.1 Supported Formats ....................................................................................................................... 5 2.2 Code Snippets ............................................................................................................................... 5

Client Side Examples with AJAX ............................................................................................................ 5 2.3 Server Side Examples with C# ....................................................................................................... 8

Get AccessToken Method ..................................................................................................................... 8 Use Token to Call Endpoint Code.......................................................................................................... 9 3. Testing Web API End Points ................................................................................................................ 10 Swagger................................................................................................................................................... 10 4. Available Endpoints............................................................................................................................. 10 4.1 Get Access Token (POST) ............................................................................................................ 10 4.2 eLot Notice (POST) ...................................................................................................................... 11 4.3 Get Trade Unit Status (GET) ........................................................................................................ 14 4.4 Get Trade Unit By Verification Key (GET).................................................................................... 15 4.5 Get Trade Units By eLot Key (GET).............................................................................................. 16 4.6 Add Inspection Result (POST) ..................................................................................................... 16 4.7 Update Inspection Result (POST) ................................................................................................ 17 Application for TUR Web API Access ...................................................................................................... 19

Page 2 of 19

eLOT Notice and Trade Unit Register Web API Guide

Introduction

The Trade Unit Register (TUR) has been introduced as a central database in the official export certification system to store relevant data around trade 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 Notice step has been introduced in the certification process, and was included for two main purposes. Firstly, the eLOT Notice is a means for trade 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 from entering the supply chain right at the start of the supply chain. This guide discusses the eLotNotice 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 trade 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 change log of the new changes and features. The Swagger page will be updated accordingly with these new features.

Page 3 of 19

eLOT Notice and Trade Unit Register Web API Guide

The links to the swagger pages are as follows:

PRODUCTION -

TESTING

-

NB! The URLs have been published here to direct clients for future use. Clients will only obtain meaningful responses back from the service from the 22nd August 2019, by which time supporting functionality will have been implemented.

Pre-requisites

The pre-conditions for a consuming system to be able to use the TUR Web APIs are as follows:

The consuming system must belong or be associated to a registered business in the Central Business Register ()

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)

1. How to register Client on User Authentication Service (UAS)

To register as a new Client on the UAS, users will need to fill in a registration form (please see Appendix 1) which they will send to support@ecert.co.za. The fields to be filled in on the form are as follows:

First Name:

First Name of Client contact

Last Name:

Last Name of Client Contact

Company Name:

Company Name for which the Client system belongs

Email Address:

Email address of Contact

Phone Number:

Contact phone number

Cell Number:

Contact cell number

Once a Client has been registered successfully the contact person will receive a notification via email with the ClientId, Base64Secret and Authentication URL. The ClientId and Base64Secrets in turn will be used by the client to Authorise 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.

2. How to Connect

As a registered client, you will receive a Client Id issued by the service provider which will be used to authenticate each request. The client Id must be sent as part of the request in the Request Header as shown below:

e.g. Client_Id: `a3acf7cf470b4d5fbb9fe6fd4b77c3a0'

Page 4 of 19

eLOT Notice and Trade Unit Register Web API Guide

2.1 Supported Formats

Messages (data) are delivered via two response types namely XML and JSON. In order to receive data in a specific format, you need to specify the content type in the response header as such: Content-Type: `application/xml' Or Content-Type: `application/json'

2.2 Code Snippets Client Side Examples with AJAX

Below are example code snippets to illustrate how to call the TUR API endpoints using AJAX on the Client side. The examples show how clients can specify which format they want to receive as a response between Json and XML.

Page 5 of 19

 ................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download