ETHIOPIA ERCA eCMS PROJECT

SOFTWARE REQUIREMENTS SPECIFICATION

E-MANIFEST WEB SERVICE DOCUMENTATION
Document Name e-Manifest Web Service Documentation

Document Number WFET-CMS-SRS-0007

General Description e-Manifest Web Service

Target Audience ERCA, WF, Carriers

Security Notice:The information contained within this document is CONFIDENTIAL. Unauthorized disclosure is prohibited.
Failure to observe Webb Fontaine guidelines regarding proprietary information can result in disciplinary action, including dismissal,
and can subject you and/or third parties to legal liability.
 ETHIOPIA ERCA eCMS PROJECT

DOCUMENT SUMMARY

Subject: Electronic Manifest

Version: 2.0

Issue Date: 22/05/2018

Circulation: ERCA, WF, Carriers

Prepared by: Amalya Tunyan

Language: English

Status: FINAL
 Ethiopa ERCA eCMS Project

Table of Contents

CHANGE CONTROL SUMMARY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

1. INTRODUCTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

2. OVERVIEW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.1 TECHNICAL OVERVIEW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.2 ARCHITECTURE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.3 USED IATA CARGO-XML MESSAGES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.4 AVAILABLE OPERATIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.5 WEB SERVICE URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.6 WEB SERVICE SECURITY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

3. THE FLOW OF OPERATIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

3.1 MANIFEST OPERATIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
3.2 WAYBILL OPERATIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
3.3 MASTER WAYBILL OPERATIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
3.4 HOUSE WAYBILL OPERATIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

4. WEB SERVICE OPERATIONS' DESCRIPTION . . . . . . . . . . . . . . . . . . . 16

4.1 OPERATION 'LOGIN' . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
4.2 OPERATION 'STORE' . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
4.2.1 Operation 'store' for Flight Manifest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
4.2.2 Operation 'store' for Waybill . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
4.2.3 Operation 'store' for House Waybill . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
4.3 OPERATION 'UPDATE' . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
4.4 OPERATION 'REGISTERMANIFEST' . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
4.5 OPERATION 'REGISTERBOL' . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
4.6 OPERATION 'DEGROUPMASTER' . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Page 3 of 27 Copyright © WEBB FONTAINE

This document, property of the issuing firm, cannot be
WFET-CMS-SRS-0007
reproduced nor communicated without written authorization.
v2.0
 Ethiopa ERCA eCMS Project

Page 4 of 27 Copyright © WEBB FONTAINE

This document, property of the issuing firm, cannot be
WFET-CMS-SRS-0007
reproduced nor communicated without written authorization.
v2.0
 Ethiopa ERCA eCMS Project

CHANGE CONTROL SUMMARY

Version Issue Date Authors Description

0.1 08/12/2017 Amalya Tunyan Draft (for review)

1.0 15/04/2018 Grigor Babayan Final version

2.0 22/05/2018 Amalya Tunyan Updated operation response messages

Removed 'addWayillList' operation

Page 5 of 27 Copyright © WEBB FONTAINE

This document, property of the issuing firm, cannot be
WFET-CMS-SRS-0007
reproduced nor communicated without written authorization.
v2.0
 Ethiopa ERCA eCMS Project

1. INTRODUCTION

The e-Manifest Web Service enables users to exchange Manifest data electronically in IATA’s
Cargo-XML format with ERCA's Electronic Customs Management System (ECMS).
This document assumes that you are familiar with IATA’s Cargo-XML standard and functionality.
This document also assumes familiarity with web services in general, and with the programming
language you will be using.

Page 6 of 27 Copyright © WEBB FONTAINE

This document, property of the issuing firm, cannot be
WFET-CMS-SRS-0007
reproduced nor communicated without written authorization.
v2.0
 Ethiopa ERCA eCMS Project

2. OVERVIEW

The e-Manifest Web Service is used to allow the Client to store, register, update Flight Manifests,
Waybills, House Waybills and degroup Master Waybills.

2.1 TECHNICAL OVERVIEW

Technical Background required for API clients:

Web Application Development,
REST API.

Page 7 of 27 Copyright © WEBB FONTAINE

This document, property of the issuing firm, cannot be
WFET-CMS-SRS-0007
reproduced nor communicated without written authorization.
v2.0
 Ethiopa ERCA eCMS Project

2.2 ARCHITECTURE

The figure below describes the basic process flow for Web Service:

Page 8 of 27 Copyright © WEBB FONTAINE

This document, property of the issuing firm, cannot be
WFET-CMS-SRS-0007
reproduced nor communicated without written authorization.
v2.0
 Ethiopa ERCA eCMS Project

2.3 USED IATA CARGO-XML MESSAGES

These are the IATA Cargo-XML messages used / supported by e-Manifest web service.

# Acronym Message Name Document Document Name

Number

1 XFFM XML Flight 122 Flight Manifest

Manifest

2 XFWB XML Waybill 740 Air Waybill

3 XFWB XML Master 741 Master Waybill

Waybill

4 XFZB XML House Waybill 703 House Waybill

5 XFNM XML Response 294 Acknowledgement and error report

Message

2.4 AVAILABLE OPERATIONS

e-Manifest Web Service provides following operations:

# Operation Document Comment

1 login Authenticates the web service user. If

authentication is successful provided
authentication token to be used in other
functions.

2 store Flight Manifest Stores a Flight Manifest, Waybill and House

Waybill with corresponding XML files.
Waybill
Master Waybill
House Waybill

3 update Flight Manifest

Page 9 of 27 Copyright © WEBB FONTAINE

This document, property of the issuing firm, cannot be
WFET-CMS-SRS-0007
reproduced nor communicated without written authorization.
v2.0
 Ethiopa ERCA eCMS Project

# Operation Document Comment

Waybill
Updates a Flight Manifest, Waybill and
Master Waybill House Waybill with corresponding XML file.
House Waybill

4 registerManifest Flight Manifest Request in JSON fromat is used to register

the Manifest.

5 registerBol Waybill Request in JSON fromat is used to register

the Waybill.
Master Waybill

6 degroupMaster Master Waybill Request in json type is used to register the

House Waybills that belong to a specific
Master Waybill.

2.5 WEB SERVICE URL

e-Manifest Web Service operations are accessed by URL.

The operation URL consists of [ base URL ][ operation path ]
Base URLs for Test and Production environments are as following:

Environment Base URL

Test https://customs.erca.gov.et/etuat-iata-manifest/api

Production https://customs.erca.gov.et/iata-manifest/api

Operation paths will be provided along with each operation description in section 4. Web Service
Operations Description .

2.6 WEB SERVICE SECURITY

Any operation requires authentication, (should be accompanied with authentication token retrieved
by 'login' method).
The information is being exchanged over HTTPS encrypted protocol.

Page 10 of 27 Copyright © WEBB FONTAINE

This document, property of the issuing firm, cannot be
WFET-CMS-SRS-0007
reproduced nor communicated without written authorization.
v2.0
 Ethiopa ERCA eCMS Project

3. THE FLOW OF OPERATIONS

This section describes the flow operations for each document.

Page 11 of 27 Copyright © WEBB FONTAINE

This document, property of the issuing firm, cannot be
WFET-CMS-SRS-0007
reproduced nor communicated without written authorization.
v2.0
 Ethiopa ERCA eCMS Project

3.1 MANIFEST OPERATIONS

The flow chart below describes the main operational flow for Manifest:
Preconditions:

1. Web Service user need to be authenticated.

Page 12 of 27 Copyright © WEBB FONTAINE

This document, property of the issuing firm, cannot be
WFET-CMS-SRS-0007
reproduced nor communicated without written authorization.
v2.0
 Ethiopa ERCA eCMS Project

3.2 WAYBILL OPERATIONS

The flow chart below describes the main operational flow for Waybill:
Preconditions:

1. Web Service user need to be authenticated.

2. Corresponding Flight Manifest document should already exist in the system.

Page 13 of 27 Copyright © WEBB FONTAINE

This document, property of the issuing firm, cannot be
WFET-CMS-SRS-0007
reproduced nor communicated without written authorization.
v2.0
 Ethiopa ERCA eCMS Project

3.3 MASTER WAYBILL OPERATIONS

The flow chart below describes the main operational flow for Master Waybill:
Preconditions:

1. Web Service user need to be authenticated.

2. Corresponding Flight Manifest document should already exist in the system.

Page 14 of 27 Copyright © WEBB FONTAINE

This document, property of the issuing firm, cannot be
WFET-CMS-SRS-0007
reproduced nor communicated without written authorization.
v2.0
 Ethiopa ERCA eCMS Project

3.4 HOUSE WAYBILL OPERATIONS

The flow chart below describes the main operational flow for House Waybill:
Preconditions:

1. Web Service user need to be authenticated.

2. Corresponding Flight Manifest document should already exist in the system.

3. Corresponding Master Waybill document should already exist in the system.

Page 15 of 27 Copyright © WEBB FONTAINE

This document, property of the issuing firm, cannot be
WFET-CMS-SRS-0007
reproduced nor communicated without written authorization.
v2.0
 Ethiopa ERCA eCMS Project

4. WEB SERVICE OPERATIONS' DESCRIPTION

This section describes technical details for each operation of e-Manifest Web Service.

As described each operation is accessed by URL which is consist of two parts:

[ base URL ][ operation path ]
Base URLs for Test and Production environments are provided in section 2.5 Web
Service URL.

4.1 OPERATION 'LOGIN'

The basic flow of login operation is the following:

1. The username and password are sent via Client to the provided URL.

2. During login a token is generated.

3. Every time, a new operation or request is sent, the token need to be passed as a parameter.

Operation login

Operation Path /login

Operation URL [base URL]/login

Headers Content-Type: application/json

Body JSON:

{
"username": "ws_user_username",
"password": "ws_user_password"
}

Accept JSON:
Response

Page 16 of 27 Copyright © WEBB FONTAINE

This document, property of the issuing firm, cannot be
WFET-CMS-SRS-0007
reproduced nor communicated without written authorization.
v2.0
 Ethiopa ERCA eCMS Project

{
"username": "ws_user_username",
"roles": [
"ROLE_X"
],
"access_token": "token"
}

Reject error code 401 Unauthorized

Response

Page 17 of 27 Copyright © WEBB FONTAINE

This document, property of the issuing firm, cannot be
WFET-CMS-SRS-0007
reproduced nor communicated without written authorization.
v2.0
 Ethiopa ERCA eCMS Project

4.2 OPERATION 'STORE'

Operation 'store' is supported for Flight Manifest, Waybill, Master Waybill and House Waybill
documents.

Operation store

Operation Path /xmlFile/store

Operation URL [base URL]/xmlFile/store

Documents Flight Manifest, Waybill, Master Waybill and House Waybill

Headers Content-Type: multipart/form-data, X-Auth-Token: 'token'

token is the value of access_token returned from the login operation.

Body XML Message:

XFFM (for Flight Manifest document), or
XFWB (for Master Waybill and Waybill document), or
XFZB (for House Waybill document)

Accept XML Message: XFNM Accept

Response

Reject XML Message: XFNM Reject

Response

4.2.1 Operation 'store' for Flight Manifest

When client sends the XFFM XML Message the e-Manifest Web Service stores the Flight
Manifest document.
Unique reference data
The Flight Manifest objects contain the following unique reference data:
Voyage Number,
Flight Manifest Departure Date,
Validations

Page 18 of 27 Copyright © WEBB FONTAINE

This document, property of the issuing firm, cannot be
WFET-CMS-SRS-0007
reproduced nor communicated without written authorization.
v2.0
 Ethiopa ERCA eCMS Project

When the Web Service receives request for storing Flight Manifests data, it maintains following
validations:
Correct format of XFFM XML file,
Nonexistence of the Manifest, which contains the same data.

4.2.2 Operation 'store' for Waybill

When client sends the XFWB XML Message the e-Manifest Web Service stores the Waybill or
Master Waybill document (depending on the type).
Unique reference data
The Waybill objects contain the following unique reference data:
Waybill type (Master or not),
B/L Reference Number,
Manifest Voyage Number and Departure Date. Example, ET123456/19Oct.
Validations
When the Web Service receives request for storing Waybill data, it maintains following validations:
Correct format of XFWB XML file,
Nonexistence of the Waybill, which contains the same data,
Existence of the Manifest with mentioned Voyage Number and Departure Date.

4.2.3 Operation 'store' for House Waybill

When client sends the XFZB XML Message the e-Manifest Web Service stores the House Waybill
document.
Unique reference data
The House Waybill objects contain the following unique reference data:
House Waybill reference number,
The reference number of Master Waybill to which it belongs.
Manifest Voyage Number and Departure Date. Example, ET123456/19Oct.
Validations
When the Web Service receives request for storing House Waybill data, it maintains following
validations:
Correct format of XFZB XML file,
Nonexistence of the House Waybill, which contains the same data,
Existence of the Manifest with mentioned Voyage Number and Departure Date.

Page 19 of 27 Copyright © WEBB FONTAINE

This document, property of the issuing firm, cannot be
WFET-CMS-SRS-0007
reproduced nor communicated without written authorization.
v2.0
 Ethiopa ERCA eCMS Project

Existence of the Master Waybill with mentioned reference number.

Page 20 of 27 Copyright © WEBB FONTAINE

This document, property of the issuing firm, cannot be
WFET-CMS-SRS-0007
reproduced nor communicated without written authorization.
v2.0
 Ethiopa ERCA eCMS Project

4.3 OPERATION 'UPDATE'

Operation 'update' is supported for Flight Manifest, Waybill, Master Waybill and House Waybill
documents. System allows to update the documents only if they are in "Stored" status.

Operation update

Operation Path /xmlFile/update

Operation URL [base URL]/xmlFile/update

Documents Flight Manifest, Waybill, Master Waybill and House Waybill

Headers Content-Type: multipart/form-data, X-Auth-Token: 'token'

token is the value of access_token returned from the login operation.

Body XML Message:

XFFM (for Flight Manifest document), or
XFWB (for Master Waybill and Waybill document), or
XFZB (for House Waybill document)

Accept XML Message: XFNM Accept

Response

Reject XML Message: XFNM Reject

Response

Page 21 of 27 Copyright © WEBB FONTAINE

This document, property of the issuing firm, cannot be
WFET-CMS-SRS-0007
reproduced nor communicated without written authorization.
v2.0
 Ethiopa ERCA eCMS Project

4.4 OPERATION 'REGISTERMANIFEST'

For registering Flight Manifest the client sends request in JSON format to e-Manifest Web Service.
The request contains the following data:
Voyage Numbe r and Departure Date. Example, ET123456/19Oct.
Departure Date,
Customs Office Code.
The Web Service checks whether there is any missing parameter or not. If there is not any
missing parameter, Web Service registers the Flight Manifest and sends response about a
successful registration in JSON format.

Operation registerManifest

Operation Path /document/registerManifest

Operation URL [base URL]/document/registerManifest

Documents Flight Manifest

Headers Content-Type: multipart/form-data, X-Auth-Token: 'token'

token is the value of access_token returned from the login operation.

Body JSON:

{
"voyageNumber": "X",
"dateOfDeparture": "Y",
"officeCode": "Z"
}

Accept JSON:
Response
{

status: 200,
error: "OK",
message: "

Page 22 of 27 Copyright © WEBB FONTAINE

This document, property of the issuing firm, cannot be
WFET-CMS-SRS-0007
reproduced nor communicated without written authorization.
v2.0
 Ethiopa ERCA eCMS Project

manifestRegister
operation succeeded."
}

Reject JSON:
Response
{
status: 400,
error: "Bad Request",
message: "error message"
}

Page 23 of 27 Copyright © WEBB FONTAINE

This document, property of the issuing firm, cannot be
WFET-CMS-SRS-0007
reproduced nor communicated without written authorization.
v2.0
 Ethiopa ERCA eCMS Project

4.5 OPERATION 'REGISTERBOL'

The basic flow of registering Waybills via Web Service is as following:

1. User adds additional Waybill to already registered Flight Manifest and stores it.

2. User registers the stored waybills.

Operation registerBol

Operation Path /document/registerBol

Operation URL [base URL]/document/registerBol

Documents Waybill, Master Waybill

Headers Content-Type: multipart/form-data, X-Auth-Token: 'token'

token is the value of access_token returned from the login operation.

Body JSON:

{
"voyageNumber": "X",
"dateOfDeparture": "Y",
"officeCode": "Z",
"bolReference": "C"
}

Accept JSON:
Response
{

status: 200,
error: "OK",
message: "bolRegister operation succeeded."

Reject JSON:
Response
{
status: 400,

Page 24 of 27 Copyright © WEBB FONTAINE

This document, property of the issuing firm, cannot be
WFET-CMS-SRS-0007
reproduced nor communicated without written authorization.
v2.0
 Ethiopa ERCA eCMS Project

error: "Bad Request",

message: "error message"
}

Page 25 of 27 Copyright © WEBB FONTAINE

This document, property of the issuing firm, cannot be
WFET-CMS-SRS-0007
reproduced nor communicated without written authorization.
v2.0
 Ethiopa ERCA eCMS Project

4.6 OPERATION 'DEGROUPMASTER'

Operation 'degroupMaster' is used to register House Waybills.

Validations
The sum of gross mass and number of packages of all House Waybills should be equal to the
gross mass and number of packages of the Master Waybill.

Operation degroupMaster

Operation Path /document/degroupMaster

Operation URL [base URL]/document/degroupMaster

Documents House Waybill

Headers Content-Type: multipart/form-data, X-Auth-Token: 'token'

token is the value of access_token returned from the login operation.

Body JSON:

{
"voyageNumber": "X",
"dateOfDeparture": "Y",
"officeCode": "Z",
"bolReference": "C"
}

Accept JSON:
Response
{

status: 200,
error: "OK",
message:"degroupMaster operation succeeded."

Reject JSON:
Response

Page 26 of 27 Copyright © WEBB FONTAINE

This document, property of the issuing firm, cannot be
WFET-CMS-SRS-0007
reproduced nor communicated without written authorization.
v2.0
 Ethiopa ERCA eCMS Project

{
status: 400,
error: "Bad Request",
message: "error message"
}

Page 27 of 27 Copyright © WEBB FONTAINE

This document, property of the issuing firm, cannot be
WFET-CMS-SRS-0007
reproduced nor communicated without written authorization.
v2.0