eCert Web API

Purpose of Document #

This document demonstrates the step by step process of setting up and using the eCert Web API methods to perform an application for an electronic Phytosanitary certificate from the request to the issuance of the certificate. To interact with the eCert Web API, client systems need to be registered.

Download the PDF #

Download the latest eCert Web API Guide

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 Web API for ePhyto requests 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 Notice 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 How to Connect to Web API Document

Testing Web API Endpoints #

To test the eCert Web API endpoints users can use 3rd party tools like Swagger or Postman. These tools will help the user get a feel of what the endpoint parameters look like, as well as view the responses in various formats. Following is the endpoint to the QA eCert API to see the available standards:

Swagger #

Available Methods #

Apply for ePhyto Certificate (eCert): POST #

PLEASE NOTE: this is currently reserved for Fruit.

Used to apply for ePhyto certificate by submitting all the necessary information to process the application.

Endpoint:

Request (xml, json):

ParameterDescriptionDatatypeRequired?Example/ Ref
–CertificateRequest    
ApplicationReferenceNoApplication Reference NumberStringNoe.g. NPPO-ZA/2020/4/25001
ApplicationTypeThe type of applicationIntYese.g. 851 (for Phytosanitary Certificate) or 657 (for Reexport)
ApplicationStatusThe status of the applicationStringYese.g. P (for Provisional), S (for Submit), U (for Update)
CBRIDThe owner of the consignmentIntYese.g. 3 Central Business Register
CBRBillingIDThe responsible person to billIntYese.g. 45 Central Business Register
CustomReferenceNoSent by the consumer to reference their systemStringNoe.g. 2016044
AgreementCodeThe agreement codeStringYese.g. AGM0001 Agreements
DesiredIssueLocationThe location where Phyto will be issuedStringYese.g. Durban, Cape Town
NotificationEmailEmail address for the individual to be notified of progressStringNoe.g. bob@fruit.co.za
ConsignorIdExporter codeStringNoe.g. D9999
ConsignorNameName of exporterStringYese.g. Overlake Farm
ConsignorAddressLine1Exporter address line 1StringYes 
ConsignorAddressLine2Exporter address line 2StringNo 
ConsignorAddressLine3Exporter address line 3StringNo 
ConsigneeIdThe party importing the consignment’s business codeStringNoe.g. VDLANS
ConsigneeNameConsignee nameStringYese.g. VAN DER LANS INTERNATIONAL B.V.
ConsigneeAddressLine1Consignee address line 1StringYes 
ConsigneeAddressLine2Consignee address line 2StringNo 
ConsigneeAddressLine3Consignee address line 3StringNo 
ConsigneeCountryIdConsignee’s countryLookupYese.g. “NL” Country ISO Alpha-2 Code
ImportCountryIdImporting CountryLookupYese.g. “NL” Country ISO Alpha-2 Code
TargetCountryIdThe country where the goods are being delivered toLookupYese.g. “NL” Country ISO Alpha-2 Code
UnloadingBaseportLocationThe final port of consignment unloadLookupYese.g. RTM Locations  
TransportModeCodeType of transport usedLookupYese.g. 1 (Maritime Transport) Modes of Transport
TransportMeansThe means of transportStringNoe.g. Container Vessel
PaymentTypeThe method of payment to be usedStringYese.g  Cash or Account
DALRRDAccNumThe Account Number to be usedStringNoeg: DAL5051A

Note: If Account is selected the DALRRDAccNum is required
>> ConsignmentItems
>>> ConsignmentItem
DescriptionProduct DescriptionStringNoe.g.  Crimson Seeds
CommonNameGeneral product nameStringYese.g. Mandarins Standards = ScientificNameOfPlant
ScientificName The scientific name of the productString e.g Citrus Sinensis
NetWeightMeasureCodeUnit of measure for net weightLookupYese.g. KGM Units of Measures Codes
NetWeightMeasureNet weightDecimalYese.g. 23315.234
GrossWeightMeasureCodeUnit of measure for the gross weightStringYese.g. KGM Units of Measures Codes
GrossWeightMeasureGross weightDecimalYese.g. 23320.234
CustomsHarmonizedSystemClassHarmonized system codeStringNoe.g. 000000
CommodityVegetablePartType of commodity classLookupNoe.g. Fruits Commodity Class Codes
CommodityConditionClassCondition of commodityLookupNoe.g. Fresh Commodity Conditions
CommodityIntentOfUseClassCommodity’s intent of useLookupNoe.g. Consumption Commodity Intent Of Use List
AppliedProcessStartDateTreatment Start DateStringNoW3 Format YYYY-MM-DDThh:mmTZD(1997-07-16T19:20+01:00)  
AppliedProcessEndDateTreatment End DateStringNoW3 Format YYYY-MM-DDThh:mmTZD(1997-07-16T19:20+01:00)  
DurationMeasureCodeUnit code for the duration of treatmentStringNoe.g. H – Hours or D – Days
DurationMeasureDuration of treatmentDecimalNoe.g. 3
AppliedProcessTreatmentTypeLevel1Treatment Type Level 1LookupNoe.g. TPT Treatment Types
AppliedProcessTreatmentTypeLevel2Treatment Type Level 2LookupNoe.g. CT Treatment Types
AppliedProcessChemicalCodeChemical IngredientLookupNoe.g. Clothianidin Active Ingredient List
AppliedProcessTemperatureUnitCodeUnit of measure for temperatureLookupNoe.g. HUR Units of Measures Codes
AppliedProcessTemperatureTemperature appliedDecimalNoe.g. 0.6
AppliedProcessConcentrationUnitCodeUnit of measure for concentrationStringNoe.g. GM Units of Measures Codes
AppliedProcessConcentrationConcentration LevelDecimalNoe.g. 2.5
AppliedProcessAdditionalNoteAdditional notes for treatmentsStringNo 
FullTreatmentInformationSummary of the full treatment as would appear on the Phyto. (Free-text field used to capture the entire treatment information)StringNoe.g. Date: 2011-11-30; Type:Chemical; Duration: 3 h; Temperature: 32 C; Concentration: 2.5 ml/kg; AdditionalInformation: No additional Information available
PackageLevelCodePackage LevelIntNoe.g. Default = 1
PackageTypeCodePackage TypeLookupYese.g. CT Packaging Codes
PackageItemUnitCodeUnit of code to quantify the packaged itemLookupYese.g. H87 (Default) Units of Measures Codes
PackageItemQuantityQuantity of packaged itemsIntYese.g. 1435
PackageShippingMarksVisible Shipping MarksStringYese.g. NONE (default) if there are no codes, or e.g. SZLU96455026
AdditionalConsignmentNotesAdditional notes or declarations for consignmentStringNoe.g. The shipment was inspected and found free of Trogoderma variable.
SequenceNumeric A number used  to uniquely identify a consignment  for updatesIntYese.g 1
<<< ConsignmentItem    
<< ConsignmentItems    
>> AdditionalInformation    
LoadSeaPointLoading Sea PortStringYese.g. ZACPT
TargetCountryThe country where the goods are being delivered toLookupYese.g. Netherlands
TargetRegionThe region where the goods are being delivered toLookupYese.g Gelderland
PortOfEntryFirst Port of EntryStringYese.g. RTM Standards = Location
BookingRefBooking ReferenceStringNoe.g. 032CAL1617983
VesselName of the vessel shippingStringNoe.g. MSC Sofia Celeste
VoyageNumberVoyager NumberStringNoe.g. NZ738R
DepartureDateDate of departureStringYesW3 Format YYYY-MM-DD
TemperatureRegimeTemperature RegimeStringNoe.g. EW001
>>> TradeUnits
>>>> TradeUnit
TradeUnitIDTrade Unit’s unique identifierStringYese.g.GS1 – SSCC format
ClientRefClient reference for trade unitStringNoe.g. Z129
PUCOperator code of growerStringYese.g. L1147
OrchardOrchard codeStringNoe.g. JB1A
OrchardPhytoStatusStatus of orchardStringYese.g. EUA1——
PHCPackhouse codeStringYese.g. L0748
ProductionAreaThe region where produce derivedStringYese.g. EC Standards = Province
CommodityCommodityStringYese.g. SC Standards = Commodity
MarketingIndicationMarket indicatorStringYese.g. MRR Standards = MarketingIndication
FleshColourColour of product’s fleshStringNoe.g. White Flesh (Applies only to Peaches & Nectarines)
ClassClassStringYese.g. 1
ContainerNumberContainer’s numberStringNoe.g. CRLU1319539
NumberOfPackagedItemsThe number of packaged items on trade unit.IntYese.g. 19
NetTradeUnitWeightTrade Unit weightDecimalYese.g. 304.234
NettPalletWeightPallet weightDecimalNoe.g. 304.234 (To be deprecated – use NetTradeUnitWeight)
PPECBInspectionDateDate PPECB performed the inspectionStringYesW3 Format YYYY-MM-DD
StuffDateStuff dateStringYesW3 Format YYYY-MM-DD
InspectionManifestNoInspection Manifest No.StringYese.g. KO00010723
InspectionPointLocationCodeInspection Point location codeIntYese.g. 3055
<<<< TradeUnit
<<< TradeUnits
<< AdditionalInformation
>> DisplayData (Properties used to override the information displayed on the Phyto document)
NumberAndDescriptionOfPackageNumber and description of PackageStringNoe.g. 20 PALLETS 3600 CARTONS GRAPES
BotanicalNameThe scientific name of the plantStringNoe.g. CITRUS LIMON
DistinguishingMarksDistinguishing markersStringNoe.g. TRIU8999152
PlaceOfOriginPlace of originStringNoe.g. SOUTH AFRICA – WESTERN CAPE
DeclaredMeansOfConveyanceMeans of conveyanceStringNoe.g. MOL PROFICIENCY 196A
DeclaredPointOfEntryFirst Point of  EntryStringNoe.g. Hamburg via Rotterdam
NameOfProductAndDeclaredQuantityName of the product and declared quantityStringNoe.g. GRAPES – 16200.00 KG NETT
TreatmentDateDate of treatmentStringNoe.g. 12 DECEMBER 2019 12H00
TreatmentType of treatmentStringNoe.g. IN TRANSIT COLD TREATMENT
ChemicalType of chemical appliedStringNoe.g  XXXXXXXXXXXXXXX
DurationAndTemperatureLength of treatment and temperature appliedStringNoe.g. -0.55 C OR BELOW FOR 22 CONSECUTIVE DAYS
ConcentrationThe concentration of chemical applicationStringNoe.g  XXXXXXXXXXXXXXX  
AdditionalInformationAny additional treatment informationStringNoe.g. Date: 2011-11-30; Type:Chemical; Duration: 3 h; Temperature: 32 C; Concentration: 2.5 ml/kg; AdditionalInfomation: No additional Information available
<<DisplayData
>> CertificateFlexiFields
>>> CertificateFlexiField
NameName of the Flexi fieldStringNoe.g. RegimeCode, ImportNo, etc.
ValueValue of Flexi fieldAnyNoe.g. NZ738R
<<< CertificateFlexiField
<< CertificateFlexiFields
>> CertificateDocuments
>>> CertificateDocument
NameThe name of the document to be uploadedStringYese.g. Cold Treatment Certificate
DocumentTypeIdThe type of documentIntYese.g. 1 Standards = DocumentType
MimeTypeThe mime type of the documentStringYese.g. Standards = MimeType
ContentSerialized Document DataStringYesBase64 Encoded String (i.e. Byte[] converted to Base64 code)
IsPrintableCan the document be printedBoolNoEg: false
<<< CertificateDocument
<< CertificateDocuments
< CertificateRequest

Response:

ParameterDescriptionDatatypeExample
ApplicationRefNoThe number generated when an application has been successfully created, used for reference purposesStringe.g. 201900016
CustomReferenceNoThe consumer’s number to reference back to their system (same as request)Stringe.g. 2016044
ApplicationStatusThe state of the applicationStringe.g. New
DocumentsUploadedThe number of documents uploadedInte.g. 3
DateCreatedThe date the application was createdStringW3 Format YYYY-MM-DD
IsSuccessfulResponse statusBooleane.g. true
ResponseMessageResponse messageStringe.g. “Successfully submitted”
    

Swagger Endpoint:

Update ePhyto Certificate (eCert)-POST #

To update a draft application, submit the same object as that for making an application as shown above in the  Apply for ePhyto Certificate section.

Endpoint:  refer to  Apply for ePhyto Certificate section.

Request (xml, json):  refer to  Apply for ePhyto Certificate section.

Response: refer Apply for ePhyto Certificate section.

Please note:

Note: To simply add new documents without changing  any other application data, please refer to the Add Documents section of this document

The request parameters to pay special attention to when submitting for an update are as follows:

ApplicationReferenceNo:  Specify the application reference number to update

ApplicationStatus:  U”  indicates  update, if not specified a new application will be created

SequenceNumeric(Consignment Level): Uniquely identifies each consignment on an application

Get Certificate Data (eCert): GET #

Used to retrieve the full details of an eCert application.

Endpoint:

Request (query parameter):

ParameterDescriptionDatatypeRequired?Example/Ref
ApplicationRefNoThe identifier for Phyto applicationStringYese.g. 201900016
     

Response:

ParameterDescriptionDatatypeExample/Ref
IsSuccessfulResponse statusBooleane.g. true
ResponseMessageResponse messageStringe.g. “Successfully submitted”
DataCertificate dataObjectPlease see ‘Apply ePhyto Request’

Get Certificate PDF (eCert): GET #

Used to retrieve a pdf copy of the ePhyto certificate.

Endpoint:

Request (query parameter):

ParameterDescriptionDatatypeRequired?Example/Ref
ApplicationRefNoThe identifier for Phyto applicationStringYese.g. 201900016
     

Response:

ParameterDescriptionDatatypeExample/Ref
IsSuccessfulResponse statusBooleane.g. true
ResponseMessageResponse messageStringe.g. “Successfully submitted”
DataCertificate documentByte[] 

Get Additional Input (eCert): GET #

PLEASE NOTE: This feature is reserved for future purposes for cooling data.

Used to retrieve additional cooling data information for the application.

Endpoint:

Request (xml, json):

ParameterDescriptionDatatypeRequired?Example/Ref
ApplicationRefNoThe identifier for Phyto applicationStringYese.g. 201900016
     

Response:

ParameterDescriptionDatatypeExample/Ref
IsSuccessfulResponse statusBooleane.g. true
ResponseMessageResponse messageStringe.g. “Successfully submitted”
AdditionalInputCooling dataByte[]e.g. pdf, excel, docx, documents

Post Additional Input (eCert): POST #

PLEASE NOTE: This feature is reserved for future purposes for cooling data.

Used to post additional information for the certification process such as cooling data

Endpoint:

Request (xml, json):

ParameterDescriptionDatatypeRequired?Example/Ref
ApplicationRefNoThe identifier for Phyto applicationStringYese.g. 201900016
AdditionalInputSupporting documentsByte[]Yese.g. pdf, excel, docx, documents
     

Response:

DescriptionDatatypeExample/Ref
Response statusBooleane.g. true
Response messageStringe.g. “Successfully submitted”
   

Check Phyto Application Status (eCert): GET #

Used to get the status of a phyto application after it has been submitted.

Endpoint:

Request (xml, json):

ParameterDescriptionDatatypeRequired?Example/Ref
ApplicationRefNoThe identifier for Phyto applicationStringYese.g. 201900016
     

Response:

ParameterDescriptionDatatypeExample/Ref
IsSuccessfulResponse statusBooleane.g. true
ResponseMessageResponse messageStringe.g. “Successfully submitted”
HubTrackingNumberThe tracking number of the application on the IPPC HubStringe.g. ZANL54635645
HubTrackingStatusA status message of the applicationStringe.g. “Delivered”

Swagger Endpoint:

Add Documents (eCert):POST #

Used to  add documents  to an existing draft application

Endpoint:

Request (xml, json):

ParameterDescriptionDatatypeRequired?Example/ Ref
ApplicationReferenceNoApplicationReference Number to add the documents toStringNoe.g. NPPO-ZA/2020/4/25001
>> CertificateDocuments
>>> CertificateDocument
NameThe name of the document to be uploadedStringYese.g. Cold Treatment Certificate
DocumentTypeIdThe type of documentIntYese.g. 1 Standards = DocumentType
MimeTypeThe mime type of the documentStringYese.g. Standards = MimeType
ContentSerialized Document DataStringYesBase64 Encoded String (i.e. Byte[] converted to Base64 code)
IsPrintableCan the document be printedBoolNoEg: false
<<< CertificateDocument
<< CertificateDocuments

Response:

ParameterDescriptionDatatypeExample/Ref
IsSuccessfulResponse statusBooleane.g. true
ResponseMessageResponse messageStringe.g. “Successfully submitted”

Swagger Endpoint:

Get List of Agreements (eCert): GET #

Used to get a list of available agreements

Endpoint:

Request (xml, json):

ParameterDescriptionDatatypeRequired?Example/Ref
CommodityCodeThe commodityCode to filter byStringNoe.g. GF- GRAPEFRUIT
CountryCodeThe countryCode of a country to filter by     StringNoNetherlands – NL
exportDateThe date to filter on applicable agreementsDate-time   Noe.g 07/01/2020

Response:

ParameterDescriptionDatatypeExample/Ref
IsSuccessfulResponse statusBooleane.g. true
ResponseMessageResponse messageStringe.g. “Successfully submitted”

Swagger Endpoint:

Get List of Agreements by Code (eCert): GET #

Used to get a list of available agreements by agreement code

Endpoint:

Request (xml, json):

ParameterDescriptionDatatypeRequired?Example/Ref
AgreementCodeThe agreementCode to filter byStringNoe.g Gernal_Burkina Faso – AGM0032

Response:

ParameterDescriptionDatatypeExample/Ref
IsSuccessfulResponse statusBooleane.g. true
ResponseMessageResponse messageStringe.g. “Successfully submitted”

Swagger Endpoint:

Get Data for Standard (eCert): GET #

Used to get the list of standards by specifying the standard name

Endpoint:

Request (xml, json):

ParameterDescriptionDatatypeRequired?Example/Ref
StandardNameName of the standard to retrieveStringYese.g PortOfEntry

Response:

ParameterDescriptionDatatype 
IsSuccessfulResponse statusBooleane.g. true
ResponseMessageResponse messageStringe.g. “Successfully submitted”

Swagger Endpoint:

List of Standards (eCert): Get #

Used to retrieve a list of all available standards   

Endpoint:

Response:

ParameterDescriptionDatatypeExample/Ref
IsSuccessfulResponse statusBooleane.g. true
ResponseMessageResponse messageStringe.g. “Successfully submitted”

Swagger Endpoint:

APPENDIX 1 #

Reference Documents #

Web References #