HOW TO USE EFRIS WEB SERVICE API

July 2, 2020 1
 Requirements

The Taxpayer completes the mandatory registration for EFRIS with URA.
Follow the link on "how to register for ERFIS”

Upon registration,
• Taxpayer shall be assigned a unique taxpayer I.D and virtual device I.D(s).
These I.Ds shall be shared with the taxpayer at integration. These should
be secretly kept.

• A detailed API technical document shall also be shared with the Taxpayer.

2
 Integration

Step1 Test Interface

At integration, the web service API shall be tested. Interface code T101
documented in the API technical document issued at registration shall be used.
Taxpayer will get the server time as the response.

3
 Integration
Step2 Initialization
After testing, the client's private key and the server's public key (RSA 2048bit)
shall be obtained through the process of initialization. For this, the interface
code T102 shall be used. This is also documented in the API technical
document shared upon registration.
Initialization shall under normal circumstances happen once unless there
has been change or update in keys.

The private key needs to be confidentially kept by the taxpayer.

Note:
The server public key in the response message is not encrypted, but the client private key will be
encrypted. The encryption algorithm is AES 128bit and the AES key is taxpayerId.substring(0,10) +
current date with the date format as "ddMMyy“
4
 Integration
Step 3: Get AES Key

 After initialization, the taxpayer shall obtain the AES key.

 The system will generate a new AES key for the taxpayer, and all transaction data
shall be encrypted/decrypted with the new AES key.
 The new AES key is valid for 24 hours, the client needs to have it updated every day,
and the interface code for this shall be T104
 The new AES key will be encrypted using the client's public key, and the client
should use the obtained private key for decryption.
 After calling method T104 ， Taxpayer can use method T103 to get Taxpayer
Information. The content of which shall be encrypted using the AES.

5
 Integration
Step3 Get Taxpayer Info

Note:
 The T103 interface contains some system parameters and dictionary versions.
 The client needs to save these parameters and call T103 once a day to
compare the dictionary version.
 Where the versions are inconsistent, the taxpayer need to call the
corresponding interface to update as summarized below;
Dictionary Version Field Dictionary Corresponding Interface

dictionaryVersion T115

commodityCategoryVersion T123

exciseDutyVersion T125

6
THANK YOU