eCert Agreements Web API

Introduction #

The Agreements Web API is designed to expose detailed information for agreements. An agreement is a set of rules for a product going to a market. This document is designed to guide vendors and other interested stakeholders on how to consume and interpret the agreements data.

Web API Versions #

There are three versions of the API that are available at a 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 in the URL or the consumer can to call the API 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:

• PRODUCTION – https://app.ecert.co.za/API/swagger/ui/index#/Agreement

• TESTING- http://qa.ecert.co.za/API/swagger/ui/index#/Agreement

Pre-requisites #

The pre-conditions for a client system to be able to consume the eCert Agreements, Requirements and Safeguards Web API are as follows:

• The client system must belong or be associated with a registered business in the Central Business Register
• The client system will need to be registered as a client in the User Authentication Service and issued a valid client_id and client_secret to be able to consume the endpoints
• All request calls for the eCert Agreements, Requirements and Safeguards will be authenticated using a JWT (JSON Web token) bearer token over OAuth 2.0 protocol
• The authorization grant type used by the User Authentication Service is ‘Client Credentials Grant’ (please see Appendix 1)

How to Connect #

Refer to the UAS Web API How to Connect

Agreement Endpoints #

Get Agreement List: GET #

Used to retrieve a list of all the Agreements in the eCert system by AgreementCode, CommodityCode, CountryCode, and Sector

Endpoint:

• https://app.ecert.co.za/API/v1/Agreement/GetAll (PRODUCTION)
• http://qa.ecert.co.za/API/v1/Agreement/GetAll (TESTING)

To Get Agreements by AgreementCode, CommodityCode, CountryCode, Sector or Export Date: #

Request (xml, json):

The parameters for the above endpoint are as follows:

Parameter	Description	Datatype	Required?	Example/ Ref
agreementCode	Filter by a specific agreement code	String	No	e.g. AGM0072
commodityCode	Lists all the agreements for the specified commodity	String	No	e.g. GF – GrapeFruit
sector	The HS Code to filter by	String	No	e.g. 08 – Fruit or 07 – Vegetables
countryCode	Lists all agreements for specified country code	String	No	e.g.  SA
exportDate	Lists all agreements where the exportdate is between the agreement start and enddate	DateTime	No	e.g. 2019-10-02 11:08:47

Response:

Returns a list of all the Agreements that correspond to the supplied parameter

Parameter	Description	Datatype	Example/ Ref
The array of Agreements:
AgreementCode	The agreement code	String	e.g. AGM0014
AgreementName	The name of the agreement	String	e.g. GF – GrapeFruit
StartDate	The start date the Agreement is applicable from	DateTime	e.g. 2019-09-26T00:00:00
EndDate	The end date the agreement stops being applicable	DateTime	e.g.  2020-09-26T00:00:00
Ranking	The hierarchy level of the agreement compared to other agreements	Int	100
Sectors (Array):
Name	Name of the sector	String	e.g. FRUIT
HSChapter	The HSCodes applicable to this agreement	String	e.g. 07 or 08
Countries (Array):
MasterListName	Name of the standard data	String	e.g. Country
Name	Name of the standard value	String	e.g. Netherlands
Code	Identifier for the Standard	String	e.g. NL
Commodities (Array):
MasterListName	Name of the standard data	String	e.g. Commodity
Name	Name of the standard value	String	e.g. GrapeFruit
Code	Identifier for the Standard	String	e.g. GF
FlexiFields (Array):
Name	Name of the flexible field	String	e.g. ImportPermitNumber
IsRequired	Whether the field is a required field	Boolean	e.g. true
DocumentTypes (Array):
Code	Identifier for the document type	String	e.g. 110
Name	The name of the document type	String	e.g. PPECB Signed Addendum
IsPrintable	Whether the document should be printed along with a Phyto application (future purposes)	Boolean	e.g. false
IsRequired	Whether the type of document is required	Boolean	e.g. true

[
    {
        "AgreementId": 72,
        "AgreementCode": "AGM0014",
        "AgreementName": "CITRUS_EU",
        "StartDate": "2019-09-26T00:00:00",
        "EndDate": "2020-09-25T00:00:00",
        "Ranking": 100,
        "Sectors": [
            {
                "Name": "Horticulture (Fruit & Berries)",
                "HSChapter": "08"
            }
        ],
        "Countries": [
            {
                "MasterListName": "Country",
                "Name": "Netherlands",
                "Code": "NL"
            }
        ],
        "Commodities": [
            {
                "MasterListName": "Commodity",
                "Name": "GRAPEFRUIT",
                "Code": "GF"
            }
        ],
        "FlexiFields": [
	      {
		   "Name": "PPECB Signed Addendum",
                "IsRequired": "true"
	      }
  ],
        "DocumentTypes": [
            {
                "Code": "110",
                "Name": "PPECB Signed Addendum",
                "IsPrintable": false,
                "IsRequired": true
            },
            {
                "Code": "112",
                "Name": "PPECB Export Certificate",
                "IsPrintable": true,
                "IsRequired": false
            },
            {
                "Code": "107",
                "Name": "Other",
                "IsPrintable": true,
                "IsRequired": false
            }
        ]
    }
]

Get Agreements List: GET (obsolete) #

Used to retrieve a list of all the Agreements in the eCert system

Endpoint:

• https://app.ecert.co.za/API/v1/Agreement/Get (PRODUCTION)
• http://qa.ecert.co.za/API/v1/Agreement/Get (TESTING)

To Get All Agreements: #

Request (xml, json):

The parameters for the above endpoint are as follows:

Parameter	Description	Datatype	Required?	Example/ Ref
NULL	Lists all the agreements in the eCert database	–	–	–

To Get Agreements for Specified Commodity, Country Code or Export Date: #

The parameters for the above endpoint are as follows:

Parameter	Description	Datatype	Required?	Example/ Ref
Commodity	Lists all the agreements for the specified commodity	String	No	e.g. GrapeFruit
CountryCode	Lists all agreements for specified country code	String	No	e.g.  SA
ExportDate	Lists all agreements where the exportdate is between the agreement start and enddate	Date-Time	No	e.g 2019-10-02 11:08:47

Response:

Returns a list of all the Agreements that correspond to the supplied parameter

Get Agreements by Agreement Code: GET #

Used to retrieve an Agreement based on supplied AgreementCode

Endpoint:

• https://app.ecert.co.za/API/v1/Agreement/GetByAgreementCode (PRODUCTION)
• http://qa.ecert.co.za/API/v1/Agreement/GetByAgreementCode (TESTING)

Request (xml, json):

The parameters for the above endpoint are as follows;

Parameter	Description	Datatype	Required?	Example/ Ref
AgreementCode	Returns an Agreement based on supplied agreement code	String	Yes	e.g.  AGM001

Response:

Returns a list of all the Agreements that correspond to the supplied parameter

APPENDIX 1 #

Reference Documents #

Web References #

• https://oauthlib.readthedocs.io/en/latest/oauth2/grants/credentials.html
• https://oauth.net/2/grant-types/client-credentials/