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:

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:

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 3^rd 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):

Parameter	Description	Datatype	Required?	Example/ Ref
–CertificateRequest
ApplicationReferenceNo	Application Reference Number	String	No	e.g. NPPO-ZA/2020/4/25001
ApplicationType	The type of application	Int	Yes	e.g. 851 (for Phytosanitary Certificate) or 657 (for Reexport)
ApplicationStatus	The status of the application	String	Yes	e.g. P (for Provisional), S (for Submit), U (for Update)
CBRID	The owner of the consignment	Int	Yes	e.g. 3 Central Business Register
CBRBillingID	The responsible person to bill	Int	Yes	e.g. 45 Central Business Register
CustomReferenceNo	Sent by the consumer to reference their system	String	No	e.g. 2016044
AgreementCode	The agreement code	String	Yes	e.g. AGM0001 Agreements
DesiredIssueLocation	The location where Phyto will be issued	String	Yes	e.g. Durban, Cape Town
NotificationEmail	Email address for the individual to be notified of progress	String	No	e.g. bob@fruit.co.za
ConsignorId	Exporter code	String	No	e.g. D9999
ConsignorName	Name of exporter	String	Yes	e.g. Overlake Farm
ConsignorAddressLine1	Exporter address line 1	String	Yes
ConsignorAddressLine2	Exporter address line 2	String	No
ConsignorAddressLine3	Exporter address line 3	String	No
ConsigneeId	The party importing the consignment’s business code	String	No	e.g. VDLANS
ConsigneeName	Consignee name	String	Yes	e.g. VAN DER LANS INTERNATIONAL B.V.
ConsigneeAddressLine1	Consignee address line 1	String	Yes
ConsigneeAddressLine2	Consignee address line 2	String	No
ConsigneeAddressLine3	Consignee address line 3	String	No
ConsigneeCountryId	Consignee’s country	Lookup	Yes	e.g. “NL” Country ISO Alpha-2 Code
ImportCountryId	Importing Country	Lookup	Yes	e.g. “NL” Country ISO Alpha-2 Code
TargetCountryId	The country where the goods are being delivered to	Lookup	Yes	e.g. “NL” Country ISO Alpha-2 Code
UnloadingBaseportLocation	The final port of consignment unload	Lookup	Yes	e.g. RTM Locations
TransportModeCode	Type of transport used	Lookup	Yes	e.g. 1 (Maritime Transport) Modes of Transport
TransportMeans	The means of transport	String	No	e.g. Container Vessel
PaymentType	The method of payment to be used	String	Yes	e.g  Cash or Account
DALRRDAccNum	The Account Number to be used	String	No	eg: DAL5051A Note: If Account is selected the DALRRDAccNum is required
>> ConsignmentItems
>>> ConsignmentItem
Description	Product Description	String	No	e.g.  Crimson Seeds
CommonName	General product name	String	Yes	e.g. Mandarins Standards = ScientificNameOfPlant
ScientificName	The scientific name of the product	String		e.g Citrus Sinensis
NetWeightMeasureCode	Unit of measure for net weight	Lookup	Yes	e.g. KGM Units of Measures Codes
NetWeightMeasure	Net weight	Decimal	Yes	e.g. 23315.234
GrossWeightMeasureCode	Unit of measure for the gross weight	String	Yes	e.g. KGM Units of Measures Codes
GrossWeightMeasure	Gross weight	Decimal	Yes	e.g. 23320.234
CustomsHarmonizedSystemClass	Harmonized system code	String	No	e.g. 000000
CommodityVegetablePart	Type of commodity class	Lookup	No	e.g. Fruits Commodity Class Codes
CommodityConditionClass	Condition of commodity	Lookup	No	e.g. Fresh Commodity Conditions
CommodityIntentOfUseClass	Commodity’s intent of use	Lookup	No	e.g. Consumption Commodity Intent Of Use List
AppliedProcessStartDate	Treatment Start Date	String	No	W3 Format YYYY-MM-DDThh:mmTZD(1997-07-16T19:20+01:00)
AppliedProcessEndDate	Treatment End Date	String	No	W3 Format YYYY-MM-DDThh:mmTZD(1997-07-16T19:20+01:00)
DurationMeasureCode	Unit code for the duration of treatment	String	No	e.g. H – Hours or D – Days
DurationMeasure	Duration of treatment	Decimal	No	e.g. 3
AppliedProcessTreatmentTypeLevel1	Treatment Type Level 1	Lookup	No	e.g. TPT Treatment Types
AppliedProcessTreatmentTypeLevel2	Treatment Type Level 2	Lookup	No	e.g. CT Treatment Types
AppliedProcessChemicalCode	Chemical Ingredient	Lookup	No	e.g. Clothianidin Active Ingredient List
AppliedProcessTemperatureUnitCode	Unit of measure for temperature	Lookup	No	e.g. HUR Units of Measures Codes
AppliedProcessTemperature	Temperature applied	Decimal	No	e.g. 0.6
AppliedProcessConcentrationUnitCode	Unit of measure for concentration	String	No	e.g. GM Units of Measures Codes
AppliedProcessConcentration	Concentration Level	Decimal	No	e.g. 2.5
AppliedProcessAdditionalNote	Additional notes for treatments	String	No
FullTreatmentInformation	Summary of the full treatment as would appear on the Phyto. (Free-text field used to capture the entire treatment information)	String	No	e.g. Date: 2011-11-30; Type:Chemical; Duration: 3 h; Temperature: 32 C; Concentration: 2.5 ml/kg; AdditionalInformation: No additional Information available
PackageLevelCode	Package Level	Int	No	e.g. Default = 1
PackageTypeCode	Package Type	Lookup	Yes	e.g. CT Packaging Codes
PackageItemUnitCode	Unit of code to quantify the packaged item	Lookup	Yes	e.g. H87 (Default) Units of Measures Codes
PackageItemQuantity	Quantity of packaged items	Int	Yes	e.g. 1435
PackageShippingMarks	Visible Shipping Marks	String	Yes	e.g. NONE (default) if there are no codes, or e.g. SZLU96455026
AdditionalConsignmentNotes	Additional notes or declarations for consignment	String	No	e.g. The shipment was inspected and found free of Trogoderma variable.
SequenceNumeric	A number used  to uniquely identify a consignment  for updates	Int	Yes	e.g 1
<<< ConsignmentItem
<< ConsignmentItems
>> AdditionalInformation
LoadSeaPoint	Loading Sea Port	String	Yes	e.g. ZACPT
TargetCountry	The country where the goods are being delivered to	Lookup	Yes	e.g. Netherlands
TargetRegion	The region where the goods are being delivered to	Lookup	Yes	e.g Gelderland
PortOfEntry	First Port of Entry	String	Yes	e.g. RTM Standards = Location
BookingRef	Booking Reference	String	No	e.g. 032CAL1617983
Vessel	Name of the vessel shipping	String	No	e.g. MSC Sofia Celeste
VoyageNumber	Voyager Number	String	No	e.g. NZ738R
DepartureDate	Date of departure	String	Yes	W3 Format YYYY-MM-DD
TemperatureRegime	Temperature Regime	String	No	e.g. EW001
>>> TradeUnits
>>>> TradeUnit
TradeUnitID	Trade Unit’s unique identifier	String	Yes	e.g.GS1 – SSCC format
ClientRef	Client reference for trade unit	String	No	e.g. Z129
PUC	Operator code of grower	String	Yes	e.g. L1147
Orchard	Orchard code	String	No	e.g. JB1A
OrchardPhytoStatus	Status of orchard	String	Yes	e.g. EUA1——
PHC	Packhouse code	String	Yes	e.g. L0748
ProductionArea	The region where produce derived	String	Yes	e.g. EC Standards = Province
Commodity	Commodity	String	Yes	e.g. SC Standards = Commodity
MarketingIndication	Market indicator	String	Yes	e.g. MRR Standards = MarketingIndication
FleshColour	Colour of product’s flesh	String	No	e.g. White Flesh (Applies only to Peaches & Nectarines)
Class	Class	String	Yes	e.g. 1
ContainerNumber	Container’s number	String	No	e.g. CRLU1319539
NumberOfPackagedItems	The number of packaged items on trade unit.	Int	Yes	e.g. 19
NetTradeUnitWeight	Trade Unit weight	Decimal	Yes	e.g. 304.234
NettPalletWeight	Pallet weight	Decimal	No	e.g. 304.234 (To be deprecated – use NetTradeUnitWeight)
PPECBInspectionDate	Date PPECB performed the inspection	String	Yes	W3 Format YYYY-MM-DD
StuffDate	Stuff date	String	Yes	W3 Format YYYY-MM-DD
InspectionManifestNo	Inspection Manifest No.	String	Yes	e.g. KO00010723
InspectionPointLocationCode	Inspection Point location code	Int	Yes	e.g. 3055
<<<< TradeUnit
<<< TradeUnits
<< AdditionalInformation
>> DisplayData (Properties used to override the information displayed on the Phyto document)
NumberAndDescriptionOfPackage	Number and description of Package	String	No	e.g. 20 PALLETS 3600 CARTONS GRAPES
BotanicalName	The scientific name of the plant	String	No	e.g. CITRUS LIMON
DistinguishingMarks	Distinguishing markers	String	No	e.g. TRIU8999152
PlaceOfOrigin	Place of origin	String	No	e.g. SOUTH AFRICA – WESTERN CAPE
DeclaredMeansOfConveyance	Means of conveyance	String	No	e.g. MOL PROFICIENCY 196A
DeclaredPointOfEntry	First Point of  Entry	String	No	e.g. Hamburg via Rotterdam
NameOfProductAndDeclaredQuantity	Name of the product and declared quantity	String	No	e.g. GRAPES – 16200.00 KG NETT
TreatmentDate	Date of treatment	String	No	e.g. 12 DECEMBER 2019 12H00
Treatment	Type of treatment	String	No	e.g. IN TRANSIT COLD TREATMENT
Chemical	Type of chemical applied	String	No	e.g  XXXXXXXXXXXXXXX
DurationAndTemperature	Length of treatment and temperature applied	String	No	e.g. -0.55 C OR BELOW FOR 22 CONSECUTIVE DAYS
Concentration	The concentration of chemical application	String	No	e.g  XXXXXXXXXXXXXXX
AdditionalInformation	Any additional treatment information	String	No	e.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
Name	Name of the Flexi field	String	No	e.g. RegimeCode, ImportNo, etc.
Value	Value of Flexi field	Any	No	e.g. NZ738R
<<< CertificateFlexiField
<< CertificateFlexiFields
>> CertificateDocuments
>>> CertificateDocument
Name	The name of the document to be uploaded	String	Yes	e.g. Cold Treatment Certificate
DocumentTypeId	The type of document	Int	Yes	e.g. 1 Standards = DocumentType
MimeType	The mime type of the document	String	Yes	e.g. Standards = MimeType
Content	Serialized Document Data	String	Yes	Base64 Encoded String (i.e. Byte[] converted to Base64 code)
IsPrintable	Can the document be printed	Bool	No	Eg: false
<<< CertificateDocument
<< CertificateDocuments
< CertificateRequest

Response:

Parameter	Description	Datatype	Example
ApplicationRefNo	The number generated when an application has been successfully created, used for reference purposes	String	e.g. 201900016
CustomReferenceNo	The consumer’s number to reference back to their system (same as request)	String	e.g. 2016044
ApplicationStatus	The state of the application	String	e.g. New
DocumentsUploaded	The number of documents uploaded	Int	e.g. 3
DateCreated	The date the application was created	String	W3 Format YYYY-MM-DD
IsSuccessful	Response status	Boolean	e.g. true
ResponseMessage	Response message	String	e.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):

Parameter	Description	Datatype	Required?	Example/Ref
ApplicationRefNo	The identifier for Phyto application	String	Yes	e.g. 201900016

Response:

Parameter	Description	Datatype	Example/Ref
IsSuccessful	Response status	Boolean	e.g. true
ResponseMessage	Response message	String	e.g. “Successfully submitted”
Data	Certificate data	Object	Please see ‘Apply ePhyto Request’

Get Certificate PDF (eCert): GET #

Used to retrieve a pdf copy of the ePhyto certificate.

Endpoint:

Request (query parameter):

Parameter	Description	Datatype	Required?	Example/Ref
ApplicationRefNo	The identifier for Phyto application	String	Yes	e.g. 201900016

Response:

Parameter	Description	Datatype	Example/Ref
IsSuccessful	Response status	Boolean	e.g. true
ResponseMessage	Response message	String	e.g. “Successfully submitted”
Data	Certificate document	Byte[]

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):

Parameter	Description	Datatype	Required?	Example/Ref
ApplicationRefNo	The identifier for Phyto application	String	Yes	e.g. 201900016

Response:

Parameter	Description	Datatype	Example/Ref
IsSuccessful	Response status	Boolean	e.g. true
ResponseMessage	Response message	String	e.g. “Successfully submitted”
AdditionalInput	Cooling data	Byte[]	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):

Parameter	Description	Datatype	Required?	Example/Ref
ApplicationRefNo	The identifier for Phyto application	String	Yes	e.g. 201900016
AdditionalInput	Supporting documents	Byte[]	Yes	e.g. pdf, excel, docx, documents

Response:

Description	Datatype	Example/Ref
Response status	Boolean	e.g. true
Response message	String	e.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):

Parameter	Description	Datatype	Required?	Example/Ref
ApplicationRefNo	The identifier for Phyto application	String	Yes	e.g. 201900016

Response:

Parameter	Description	Datatype	Example/Ref
IsSuccessful	Response status	Boolean	e.g. true
ResponseMessage	Response message	String	e.g. “Successfully submitted”
HubTrackingNumber	The tracking number of the application on the IPPC Hub	String	e.g. ZANL54635645
HubTrackingStatus	A status message of the application	String	e.g. “Delivered”

Swagger Endpoint:

Add Documents (eCert):POST #

Used to  add documents  to an existing draft application

Endpoint:

Request (xml, json):

Parameter	Description	Datatype	Required?	Example/ Ref
ApplicationReferenceNo	ApplicationReference Number to add the documents to	String	No	e.g. NPPO-ZA/2020/4/25001
>> CertificateDocuments
>>> CertificateDocument
Name	The name of the document to be uploaded	String	Yes	e.g. Cold Treatment Certificate
DocumentTypeId	The type of document	Int	Yes	e.g. 1 Standards = DocumentType
MimeType	The mime type of the document	String	Yes	e.g. Standards = MimeType
Content	Serialized Document Data	String	Yes	Base64 Encoded String (i.e. Byte[] converted to Base64 code)
IsPrintable	Can the document be printed	Bool	No	Eg: false
<<< CertificateDocument
<< CertificateDocuments

Response:

Parameter	Description	Datatype	Example/Ref
IsSuccessful	Response status	Boolean	e.g. true
ResponseMessage	Response message	String	e.g. “Successfully submitted”

Swagger Endpoint:

Get List of Agreements (eCert): GET #

Used to get a list of available agreements

Endpoint:

Request (xml, json):

Parameter	Description	Datatype	Required?	Example/Ref
CommodityCode	The commodityCode to filter by	String	No	e.g. GF- GRAPEFRUIT
CountryCode	The countryCode of a country to filter by	String	No	Netherlands – NL
exportDate	The date to filter on applicable agreements	Date-time	No	e.g 07/01/2020

Response:

Parameter	Description	Datatype	Example/Ref
IsSuccessful	Response status	Boolean	e.g. true
ResponseMessage	Response message	String	e.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):

Parameter	Description	Datatype	Required?	Example/Ref
AgreementCode	The agreementCode to filter by	String	No	e.g Gernal_Burkina Faso – AGM0032

Response:

Parameter	Description	Datatype	Example/Ref
IsSuccessful	Response status	Boolean	e.g. true
ResponseMessage	Response message	String	e.g. “Successfully submitted”

Swagger Endpoint:

Get Data for Standard (eCert): GET #

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

Endpoint:

• https://app.ecert.co.za/api/v1/Standards/GetStandardData (PRODUCTION)

•  http://qa.ecert.co.za/api/v1/Standards/GetStandardData (TESTING)

Request (xml, json):

Parameter	Description	Datatype	Required?	Example/Ref
StandardName	Name of the standard to retrieve	String	Yes	e.g PortOfEntry

Response:

Parameter	Description	Datatype
IsSuccessful	Response status	Boolean	e.g. true
ResponseMessage	Response message	String	e.g. “Successfully submitted”

Swagger Endpoint:

List of Standards (eCert): Get #

Used to retrieve a list of all available standards   

Endpoint:

• https://app.ecert.co.za/api/v1/Standards/GetStandardList (PRODUCTION)

•  http://qa.ecert.co.za/api/v1/Standards/GetStandardList (TESTING)

Response:

Parameter	Description	Datatype	Example/Ref
IsSuccessful	Response status	Boolean	e.g. true
ResponseMessage	Response message	String	e.g. “Successfully submitted”

Swagger Endpoint:

APPENDIX 1 #

Reference Documents #

Web References #