Getting started with eECD API integration

Preface

The EFTCO cleaning Document or ECD has been turned into a digital eECD process. This digital eECD Use Case runs on the ECLIC platform, powered by NxtPort and is accessible via Open API's. Using the eECD API, or eECD Application Programming Interface, allows any company or subscriber with a valid, active and approved eECD licence to integrate the digital eECD process within an own existing legacy application, using an extensible XML interface. In case a 3rd party IT vendor application is responsible for the integration, please note that this IT vendor also needs to subscribe to the ECLIC platform before they obtain authorized access to the eECD API’s.

Authentication with valid eECD user account credentials is required for making eECD API requests to the ECLIC platform, powered by NxtPort. At registration the NxtPort, ECLIC and eECD specific Terms and Conditions need to be accepted. Furthermore, each eECD user’s account permissions correspond to the specific assigned eECD licence type and user roles within the eECD process. These permissions also apply to the allowed API calls when integrating with the eECD API.

The eECD API’s described in this guide are available to ECLIC Subscribers using the digital eECD Process running on the ECLIC platform, powered by NxtPort. If you would need assistance to obtain an eECD licence please check www.eclic.eu or contact info@eclic.eu.

Types of usage/integration of the eECD platform

Practical eECD API information

The eECD API is based on an OpenAPI specification also called swagger. An up to date version of the eECD API, its methods, and a more detailed description of the eECD API can found at the following address:

• For Staging environment https://nxtport.github.io/?api=stg.eecd

• For Production environment https://nxtport.github.io/?api=eecd

Please note this url link does not work with the Internet Explorer browser so we recommend the use of browsers like Google Chrome or Mozilla Firefox.

eECD account registration

Before any chemical,  cleaning,  transport or tank storage company can obtain access to the eECD API’s, a valid and approved eECD subscription form is required which allows to set up of an eECD admin account. Approval of the form is given by ECLIC and the form is available on www.eclic.eu.

In case an IT software vendor wants to integrate the eECD API’s and wants to offer the digital eECD process as an integrated software solution to its customers, the IT vendor need to first complete the eECD IT vendor subscription form. The eECD IT vendor subscription form can be requested via info@eclic.eu, who will also validate and approve each IT vendor subscription request.

Once you have sent an approved eECD subscription form and your form is approved by ECLIC, you can register yourself with an account to the NxtPort platform via https://www.nxtport.eu. NxtPort is an API platform that maintains multiple use cases, such as the digital eECD Use Case.

Once the NxtPort registration is complete, please create a support ticket via e-mail (eecd-support@nxtport.com) or via the ticketing portal: http://support.nxtport.com to request the necessary Client Key (see illustration in paragraph 2). The support team will help with the different environments and setting up the client ids for the eECD API.

The NxtPort platform offers two different endpoints: eECD staging or test environment and eECD production environment.

• eECD Staging: https://api-stg.nxtport.eu/eecd/v1 This is the general eECD test environment, which can be used to design, develop and test the digital eECD process within an eECD application integrated environment. New features will be developed and tested here, before being moved to production.

• eECD Production: https://api.nxtport.eu/eecd/v1 This environment is used for daily operations.

Authentication

Staging

Attention, this part will first decribe what is needed to fetch the NxtPort access tokens for the eECD Staging environment and varies a little from the set-up with the eECD Production environment. 

You can fetch NxtPort access tokens as follows.

Send a POST request to https://login-stg.nxtport.eu/connect/token with the following body (*not* parameter or header) keys:

• username: email address of a user of a company that is subscribed to the API

• password: password of a user of a company that is subscribed to the API

• grant_type: password

• client_id: Client ID of the application builder (internal or third party), provided by NxtPort

• client_secret: code to verify the client_id, also provided by NxtPort

• scope: nallian-eecdapi offline_access

The access token will be in the access_token field, and is valid for 1 hour.

Production

Please note that if in the future you wish to connect to our eECD Production environment you will require a different client_id and client_secret. After the completion of your eECD subscription, please request these key via eecd-support@nxtport.com. 

To fetch NxtPort access tokens as follows:

Send a POST request to https://login.nxtport.eu/connect/token.  with the following body keys:

• username: email address of an end-user who is subscribed to the API

• password: password of the username

• grant_type: password

• client_id: Client ID of the application builder (internal or third party), provided by NxtPort

• client_secret: code to verify the client_id, also provided by NxtPort

• scope: nallian-eecdapi offline_access

Authorization

Not every call of the eECD API is available to all companies and depends on your eECD licence subscription while some API calls are further restricted to certain eECD user roles. For a detailed overview of the licenses, authorization roles and the API calls, please refer to the Swagger description.

Create an API call

In order to call a web API:

• include the API key of the eECD subscribed company in your call: You can put the API subscription key either in the header as the Ocp-Apim-Subscription-Key parameter, or in the query string as the subscription-key parameter. This key is found in the NxtPort Console under Tab 'Data User'. 

• include a token in your call using a header parameter with name “Authorization" and value “Bearer {TOKEN}”. Replace {TOKEN} with the token that you received in your call to get the token and remove the quotes, present here just to indicate the extent of the content. The authorization token is created using the client key of the application builder. Refer to the diagram above for more details.

NxtPort API support

NxtPort is committed to providing you with the required technical eECD API support once a company has a valid eECD licence and the support questions enter the company via the mentioned support channels. Access to extra API documentation is granted via your valid & approved eECD admin account which is available via the ECLIC community page on API Integration Guidelines .

You are expected to have a sufficient level of technical knowledge to be able to use the API with reference to the eECD API documentation alone.

eECD API Basic Support (free)

Free Email technical support is available via eecd-support@nxtport.com or http://support.nxtport.com for light and infrequent queries without a response time guarantee.

eECD API Priority Support (pre-paid service package)

Should you require prompter response times or more comprehensive assistance, a pre-paid option is available upon request. Please contact eecd-support@nxtport.com to set this up.

With eECD API priority support you get the following: 

• Direct email access to an assigned eECD support officer from the NxtPort team

• Guaranteed response time within 1 business day

• API expertise via Skype and/or other screen-share consults as needed

NxtPort supports you 5 days a week during business workdays in Belgium, from 9.00-17.00 hours. Technical assistance is in relation to the eECD API protocols only and is not providing assistance with your own application source code. Support terms are for 30 days. You may renew for additional terms if required.

Other Interesting API Pre-readings

API Basic information & definitions

• API REST architecture (https://restfulapi.net)

• OAuth 2.0 authentication protocol (https://oauth.net)

• JSON API standards for handling requests (https://jsonapi.org)