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:

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:

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

Request (xml, json):

The parameters for the above endpoint are as follows:

ParameterDescriptionDatatypeRequired?Example/ Ref
agreementCodeFilter by a specific agreement codeStringNoe.g. AGM0072
commodityCodeLists all the agreements for the specified commodityStringNoe.g. GF – GrapeFruit
sectorThe HS Code to filter byStringNoe.g. 08 – Fruit or 07 – Vegetables
countryCodeLists all agreements for specified country codeStringNoe.g.  SA
exportDateLists all agreements where the exportdate is between the agreement start and enddateDateTimeNoe.g. 2019-10-02 11:08:47

Response:

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

ParameterDescriptionDatatypeExample/ Ref
The array of Agreements:   
AgreementCodeThe agreement codeStringe.g. AGM0014
AgreementNameThe name of the agreementStringe.g. GF – GrapeFruit
StartDateThe start date the Agreement is applicable fromDateTimee.g. 2019-09-26T00:00:00
EndDateThe end date the agreement stops being applicableDateTimee.g.  2020-09-26T00:00:00
RankingThe hierarchy level of the agreement compared to other agreementsInt100
Sectors (Array):   
NameName of the sectorStringe.g. FRUIT
HSChapterThe HSCodes applicable to this agreementStringe.g. 07 or 08
Countries (Array):   
MasterListNameName of the standard dataStringe.g. Country
NameName of the standard valueStringe.g. Netherlands
CodeIdentifier for the StandardStringe.g. NL
Commodities (Array):   
MasterListNameName of the standard dataStringe.g. Commodity
NameName of the standard valueStringe.g. GrapeFruit
CodeIdentifier for the StandardStringe.g. GF
FlexiFields (Array):   
NameName of the flexible fieldStringe.g. ImportPermitNumber
IsRequiredWhether the field is a required fieldBooleane.g. true
DocumentTypes (Array):   
CodeIdentifier for the document typeStringe.g. 110
NameThe name of the document typeStringe.g. PPECB Signed Addendum
IsPrintableWhether the document should be printed along with a Phyto application (future purposes)Booleane.g. false
IsRequiredWhether the type of document is requiredBooleane.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:

To Get All Agreements: #

Request (xml, json):

The parameters for the above endpoint are as follows:

ParameterDescriptionDatatypeRequired?Example/ Ref
NULLLists 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:

ParameterDescriptionDatatypeRequired?Example/ Ref
CommodityLists all the agreements for the specified commodityStringNoe.g. GrapeFruit
CountryCodeLists all agreements for specified country codeStringNoe.g.  SA
ExportDateLists all agreements where the exportdate is between the agreement start and enddateDate-TimeNoe.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:

Request (xml, json):

The parameters for the above endpoint are as follows;

ParameterDescriptionDatatypeRequired?Example/ Ref
AgreementCodeReturns an Agreement based on supplied agreement codeStringYese.g.  AGM001

Response:

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

APPENDIX 1 #

Reference Documents #

Web References #