Technical Briefing on Application Programming Interface (API)

Transcription

1 Technical Briefing on Application Programming Interface (API) TICFMB Web-Based E-Levy System Travel Industry Compensation Fund Management Board (TICFMB) 9 November 2017

2 Rundown 1. Introduction to E-levy System 2. E-Franking API Specifications 3. Generation of API Key 4. API E-Frank Demo 5. Implementation Considerations Suggested for TAs 6. Q&A 7. Evaluation 2

3 Introduction to E-levy System 3

4 What is E-levy? E-levy is a web-based system, which will enable Ø travel agents to make levy payments reload their e-levy accounts apply for refund of levies paid Ø outbound travellers to check levy payment status and hence, protection under the TICF 4

5 Some Salient Features 1. Response time for e-franking is less than 4 seconds (peak loading) 2. Calculation of levy amount may be rounded up to the nearest $ notification on reload/refund request status, low account balance and maximum levy amount reached can be provided 4. For E-Franking API, optional additional security measures including IP address restriction and two-way SSL are provided 5

6 E-levy Payment (Travel Agent) Data input Customer Conventional Booking internet E-levy System E-booking API: Application Programming Interface 6

7 E-levy Payment (Travel Agent) Data input Levy data Amount of outbound fare received Customer Conventional Booking Receipt number internet Full name internet of payer/traveller, or name of company/corporation Departure date E-levy System Last 4 digits of contact phone number E-booking API: Application Programming Interface 7

8 E-levy Payment (Travel Agent) Data returned Customer Conventional Booking E-levy stamp Levy collection internetnumber internet Levy internet data (for API only) E-levy System E-booking API: Application Programming Interface 8

9 E-levy Stamp Max C2 Franked date 14-digit levy collection number URL 23-character TA s name (Same as existing franking machines) TA s receipt number Copy number (if any) 9

10 An Important Note for Travel Agents and their Technical Staff The Travel Agents Ordinance requires that levy shall be payable in respect of every outbound fare received by a travel agent. As the API will send, amongst other data, the "amount of outbound fare received" to the E-levy System for calculation and payment of levy due, Travel Agents and their technical staff are obliged to ensure that the amount sent to the E-levy System include all items that make up the "outbound fare" as stipulated under the Travel Agents Ordinance. In setting up the API, Travel Agents and their technical staff, in-house or out-sourced, should ensure that this requirement is fully complied with in the customisation work. They should consult TIC in case of doubt about items that are subject to levy payment. 10

11 E-Franking API Specifications 11

12 API Specification 1. SOAP 1.2 over HTTPS, WSDL WSDL provided in the interface specification, for generating proxy classes with the dev tool 3. Web service endpoints, to be confirmed in later stages, currently temporary URL will be used: 4. Input fields of LevyEFrankRequest 5. Output fields of LevyEFrankResponse 6. Error codes 12

13 Input fields of LevyEFrankRequest Item Field Name Format Manda Description tory 1 API_KEY X(36) Y API Key of the Travel Agent. Should be generated / re-generated through online function 2 RECEIPT_NUMB ER X(50) Y Receipt number to be franked. Should be unique for each E-Frank record. 3 OUT_BOUND_FA RE_PAID 9(8).9(2) Y Decimal value with at most 2 decimal places is allowed. 4 NAME_OF_TRAV ELER_PAYER X(100) Y Name of the Traveler / Payer or Company in either Tranditional Chinese, Simplified Chinese or English language. The encoding 5 DEPARTURE_DA TE 6 LAST_4_DIGIT_O F_CONTACT_PH ONE_NUMBER should be UTF-8. X(10) Y Departure Date in YYYY-MM-DD format. Should not be earlier than the current date. YYYY - Year MM - Month DD - Day 9(4) Y A 4-digit numeric value of the last 4 digits of contact phone number 13

14 Output fields of LevyEFrankResponse Item Field Name Format Manda Description tory 1 ACK_CODE X(1) Y Acknowledgment code of the LevyEFrank operation. S Successful V Validation of the data element in LevyEFrankRequest failed. B Insufficient Account Balance X Other System Error 2 ACK_MESSAGE X(500) N Acknowledgment message of the LevyEFrank operation. 3 RECEIPT_NUMB ER For ACK_CODE = S, the field will be OK. For ACK_CODE = V or B or X, the field will be in the following format: [Error Code 1] Error Message 1, [Error Code 2] Error Message 2, X(50) N Same data as in the input type LevyEFrankRequest for both successful and unsuccessful LevyEFrank operations. 4 OUT_BOUND_FA 9(8).9(2) N Same data as in the input type 14

15 Output fields of LevyEFrankResponse Item Field Name Format Manda Description tory 4 OUT_BOUND_FA RE_PAID 9(8).9(2) N Same data as in the input type LevyEFrankRequest for both successful and 5 NAME_OF_TRAV ELER_PAYER 6 DEPARTURE_DA TE 7 LAST_4_DIGIT_O F_CONTACT_PH ONE_NUMBER 8 FRANK_DATE_TI ME unsuccessful LevyEFrank operations. X(100) N Same data as in the input type LevyEFrankRequest for both successful and unsuccessful LevyEFrank operations. X(10) N Same data as in the input type LevyEFrankRequest for both successful and unsuccessful LevyEFrank operations. 9(4) N Same data as in the input type LevyEFrankRequest for both successful and unsuccessful LevyEFrank operations. X(19) N Frank Date and Time in YYYY-MM-DD HH:MI:SS format. Will be empty if the LevyEFrank operation is not successful. YYYY - Year MM - Month DD - Day HH - Hour in 24-hour format MI - Minute SS Second 9 LEVY_COLLECTI X(14) N Levy Collection Number of the Levy Stamp. 15

16 Output fields of LevyEFrankResponse Item Field Name Format Manda Description tory 9 LEVY_COLLECTI ON_NUMBER X(14) N Levy Collection Number of the Levy Stamp. Will be empty if the LevyEFrank operation is unsuccessful. 10 LEVY_AMOUNT X(11) N Levy Amount. Will be empty if the 11 LOW_ACCOUNT_ BALANCE_INDIC ATOR LevyEFrank operation is unsuccessful. X(1) N Low Account Balance Indicator. Will be empty if the LevyEFrank operation is unsuccessful. 0 No Alert 1 First Alert 2 Repeated Alert 12 LEVY_STAMP BINARY N Levy Stamp file in PNG format. Will be empty if the LevyEFrank operation is unsuccessful. Size of the stamp: Width: 830 pixels Height: 236 pixels Resolution: 300 dpi Print size: About 7 cm x 2 cm 16

17 Error Codes Error Code WS-E001 WS-E002 WS-E003 WS-E004 WS-E005 WS-E006 WS-E007 WS-E008 WS-E009 WS-E010 WS-E011 Error Message Missing value of <field name>. Value of <field name> must be within <number> characters. Value of <field name> must be between <minimum value> and <maximum value>. Invalid value of <field name>. Departure Date should not be earlier than the current date. API Key not found. Receipt number not match with the pre-defined format. Same receipt number already exist in the system. Levy amount exceeded the pre-defined limit of your company. Insufficient account balance. System error. Please contact support and provide the following information: 17

18 Generation of API Key 18

19 API Key Obtain from the E-levy System by TA s User Admin 1. Login to E-levy System 2. Settings > API Settings 3. Generate API Key 19

20 Additional Security Options for API IP Address Restriction Provide 1 or more source WAN IP(s) for checking along with the API Key come with the requests. Two-way SSL Please contact E-levy support team and provide the your certificate without private key for setting up. When making request to the E-Levy API, attached your certificate as client certificate. 20

21 API E-Frank Demo 21

22 Demonstration of E-Franking API Open source SOAP testing tool SoapUI will be used 1. Copy WSDL from the interface specification to a file 2. Create a new SOAP project 3. Generate sample request 4. Test with the sample request 5. Normal case 6. Exception case 22

23 Implementation Considerations Suggested for TAs 23

24 Implementation Considerations Suggested for TAs 1. Reduce dependency between your system and the E-levy API 2. Implement a switch for release management and E-levy System scheduled maintenance 3. Check all input values before passing into the E-levy system 4. Handle exceptions returned from the E-levy API and unexpected exceptions 5. Implement retry logic for unexpected connectivity error, levy amount will not be deducted twice 6. Provide own alerts with the low account balance indicator returned from E-levy API 7. Keep the responses from E-levy System for management purpose 8. Consider whether additional security is required 24

25 Q&A 25

26 For enquires about the E-Levy System, please contact the E-Levy Project Team: Mr. Andrew Tam Tel. No.: projectelevy@deloitte.com.hk Website : 26

27