Step by step guide on how to Integrate

System2system on EFRIS
Version 1.1
Issue date 19/07/2022
What is EFRIS?
Electronic Fiscal Receipting and Invoicing Solution (EFRIS) is a government
initiative under the Domestic Revenue Mobilization Strategy (2019/20-2023/24)
that shall be used by all Value Added Tax (VAT) registered taxpayers’ businesses
to manage the issuance of e-receipts and e-invoices in accordance with Sec 73A
of the Tax Procedures Code Act 2014.

What is e-receipt/Invoice?
This is an electronic tax document issued under business models of Business to
Business (B2B), Business to Government (B2G) and Business to Consumer
(B2C) and authenticated by the central Electronic Fiscal Receipting and Invoicing
system. The e-invoicing solution has the following options available;

i. System2system integration: For clients with existing sales systems.

In this case, taxpayers shall integrate his/her existing sales system with
EFRIS and continue to use the same systems to issue e-receipts and e-
invoices. The option supports both online and offline mode.
ii. The URA web portal: Taxpayers may opt to use their accounts on the
portal to issue e-receipts and e-invoices.
iii. The Desktop (client) Application: The application can be downloaded
from the portal under downloads and uploaded onto one’s computer for
the issuance of e-receipts and e-invoices.
iv. Electronic Fiscal devices (EFD): Taxpayers may opt to use EFDs
purchased from approved suppliers to issue e-receipts and e-invoices.

User Guide-How to Integrate S2S on EFRIS Version 1.0, EFRIS Project, Process Management Division
Page | 1
 How do I integrate my existing sales system with
EFRIS?
The integration is through a web service Application Programming Interface (API)
that supports both Online Mode and Offline Mode. Below is the summary of steps
to follow to complete the integration. The detailed process for each of the steps
will be detailed further below;
Step 1 Register for EFRIS on the test environment.
Step 2 Download the latest technical documents regarding system to system
integration. The documents can be found under Downloads >>
Documents.
Step 3 If you wish to use the offline enabler you can download it from the
test environment under Downloads >> Application (Software). If you
wish to connect directly, the API endpoint is
https://efristest.ura.go.ug/efrisws/ws/taapp/getInformation
Step 4 Execute the interface codes.
Step 5 Conduct joint User Acceptance Tests with URA.
Step 6 Migrate to production.

User Guide-How to Integrate S2S on EFRIS Version 1.0, EFRIS Project, Process Management Division
Page | 2
 Step 1 EFRIS Registration
Register for EFRIS on the test environment. To register, follow the step
by step guide in the How to Register tutorial on the portal under User
Guides.

Step 2 Download technical documents.

After successful registration, download the latest technical documents
regarding system to system integration that are available on the test
portal https://efristest.ura.go.ug/efrissite >> Downloads >>
Documents as summarized below to get the required invoice/receipt
details, endpoints and interface codes.

Note: The test API URL when connecting directly is;

https://efristest.ura.go.ug/efrisws/ws/taapp/getInformation

User Guide-How to Integrate S2S on EFRIS Version 1.0, EFRIS Project, Process Management Division
Page | 3
 Step 3 Download and install the offline enabler.
a) Offline mode (Recommended)
i. The taxpayer is required to submit their digital certificate/keys to
URA by completing the EFRIS Digital Certificate form in appendix 1
to indicate the details of the digital certificate they intend to use in
the test. The form is to be signed by the Taxpayer’s Authorized
contact person(s).
ii. Upon successful completion of the EFRIS Digital Certificate
form(Appendix 1), the taxpayer is required to download and install
the offline mode installer (Windows, Ubuntu, or Linux) that
supports their application from the test portal
https://efristest.ura.go.ug/efrissite under Downloads >>
Applications (Software) as highlighted below.

iii. To Install the Offline enabler, follow the installation guide in

Appendix 2. The offline mode enabler installation guide is also
available for download from the test portal
https://efristest.ura.go.ug/efrissite under Downloads >>
Documents.
User Guide-How to Integrate S2S on EFRIS Version 1.0, EFRIS Project, Process Management Division
Page | 4
 iv. The RSA key pair generated must have a key size of 2048 and
support SHA1withRSA algorithm. To generate the key-pair we
recommend using KeyStore explorer version 5.4.4. Follow the guide
Appendix 5.
v. Upon successful completion of the installation process, the EFRIS
system shall automatically assign you a device number. To avoid
the Device Number changing in future, you will need to set the
MAC address of the computer used to be static and remain
consistent with one modem in the event that you use that as
your internet source.
vi. The taxpayer is required to register the device number and
thumbprint using the guide below in Appendix 6. The taxpayer shall
receive a notification through the registered email address when the
device registration process is completed.

b) Online Mode
i. The taxpayer is required to submit their device number and
thumbprint following the step by step guide in Appendix 6.

Step 4: Execute interface codes.

There are a couple of interface codes to support this implementation.
The order of execution of the interface codes is as follows;
Online:
1. Test the Interface using interface code T101
2. Use interface code T104 to get the symmetric (AES) key. This
will be used for encryption of the request and decryption of the
response.
3. Use Interface code T103 to log in (Not mandatory for
transaction processing).
4. Use interface code T115 for system dictionary (Not mandatory
for transaction processing).
User Guide-How to Integrate S2S on EFRIS Version 1.0, EFRIS Project, Process Management Division
Page | 5
 5. Call other interfaces as specified in the table below.

How to generate the signature.

Obtain AES key.
1. Get the response of interface T104.
2. Base64 decode the content field value in the response.
3. The value in passowrdDes is RSA encrypted using your public key, so
you have to decrypt it using your private key.
4. The value obtained after decryption is the AES key.
Encryption
5. Encrypt the request content json of the given interface using the AES
key.
6. Base64 encode the result and add it to the content field.
Signing the request.
7. Use your private key to RSA sign the content from 6.
8. Add the resulting string to the signature field.

Offline mode enabler (Supports both online and offline)

1. Download from the portal and install the offline enabler
2. Configure the public certificate on the portal and private certificate on
the offline-mode enabler.
3. Initialize the offline-mode enabler following the installation guide in
appendix 2.
4. Call other interfaces as specified in the following table.

User Guide-How to Integrate S2S on EFRIS Version 1.0, EFRIS Project, Process Management Division
Page | 6
 Module Interface Mandatory/ Interface Name Description/Remarks
Code
Optional

System set up T104 Mandatory Get symmetric key This is mandatory during
and data E and system set up for taxpayers
encryption signature information that have opted to connect
/decryption directly to the EFRIS end
point at URA without using
the offline-mode enabler.

This is required for all

interface codes where the
defined request or response is
indicated as encrypted.

T115 Mandatory System dictionary Used to map the taxpayer

update System dictionary /update
with EFRIS
Registration T119 Mandatory Query Taxpayer Used for TIN validation
Information By
TIN
T138 Optional Get all branches Used to get a list of registered
branches.

Stock T124 Optional Query Commodity Used to query/get the

management Category commodity category codes
pagination
T125 Mandatory for Query Excise Duty Used to query/get excise duty
taxpayers dealing codes. Only applicable for
in excisable taxpayers dealing in excisable
products products.
T126 Optional Get All Exchange Used to query/get exchange
Rates rates. Only applicable for

User Guide-How to Integrate S2S on EFRIS Version 1.0, EFRIS Project, Process Management Division
Page | 7
 taxpayers generating invoices
in foreign currencies.
T130 Mandatory Goods Upload Used to configure and upload
your products on to EFRIS.
However, this can also be
done through the web portal.
Stock T127 Optional Goods/Services Used to Get/inquire all your
management Inquiry products configured through
Stock interface T130 or web portal
management T127 Optional Goods/Services Used to Get/inquiry all your
Inquiry by products configured through
goods Code interface T130 or web portal
by the product code
T128 Optional Query the stock Used to Get/inquiry stock
quantity by values for a given product
goods id
T131 Optional Goods Stock Maintain Used to update stock for a
given product. However, the
Note: Only same can be updated from the
required web portal.
for goods
T139 Optional Goods Stock Transfer Used to transfer goods from
one branch to another.
However, the same can be
transferred from the web
portal.
Invoice T109 Mandatory Billing upload Used to fiscalise
Management receipts/invoices
T129 Optional Batch Invoice Upload Used to fiscalise Batch
(multiple) receipts/invoices in
a single request.
T108 Optional Invoice details Used to validate a fiscalised
receipts/invoices using;

a) Fiscal document
number(FDN)

User Guide-How to Integrate S2S on EFRIS Version 1.0, EFRIS Project, Process Management Division
Page | 8
 b) Verification code
c) QR code

T106 Optional Invoice /Receipt Used to search fiscalised

query transactions with more
search parameters other the
one in T108.
T137 Mandatory for Check taxpayer type. Used to check the
taxpayers selling exemption/VAT deeming
to persons with status for a given
special VAT taxpayer/products.
treatment
Credit note/ T110 Mandatory where Credit Application Credit notes take the
Debit Note the buyer type following process flow;
referenced to the was B2B & B2G a) Invoice is raised using
original invoice. T109
b) Credit note
application is raised using
T110. (Note that this
returns a reference to the
Note: No approval application. The credit note
is required for must be approved by URA
buyer type B2C Credit/Cancel Debit before it is considered
Note Application List fiscalised.)
Query c) Query for credit note
T110 application
status(Approved/Rejected)
using T111. Only approved
Credit notes will return the
CNN(Credit Note Number)
d) Get the verification
code and QR code using
T108.
T114 Mandatory where Credit Note Use interface code T114 to
the buyer type application cancel cancel credit/debit note that
was B2B & B2G has already been approved.

User Guide-How to Integrate S2S on EFRIS Version 1.0, EFRIS Project, Process Management Division
Page | 9
 T118 Mandatory where Query Credit Note Use interface code T118 to
the buyer type Application and cancel credit/debit note
was B2B & B2G Cancel of Debit Note application that has not been
Application Details approved.

T113 Optional Credit Note Use interface code T113 to get

application detail Credit Note application detail

Any other interface relevant to your business as specified in the API document

Support
For any support during the integration process, contact efris-it-
support@ura.go.ug. Please ensure to always specify the following whenever
available:

1. TIN
2. Device Number
3. JSON request and response.

Step 5: Conduct joint UAT online and Go live configurations.

i. After successful integration or completion of the development of EFRIS
requirement, the taxpayer is required to complete the readiness check
list in appendix 4 and share the completed form to ikamya@ura.go.ug;
sauma@ura.go.ug; tbesigye@ura.go.ug, jkayeny@ura.go.ug and
bajuna@ura.go.ug copy using the registered using the email address
registered on the TIN profile.
ii. Upon receiving the notification and the completed checklist, the
taxpayer shall be advised on the suitable date and time to conduct the
joint User Acceptance Testing (UAT)based on EFRIS Interface User
Requirements Specifications (Business Requirements) and the EFRIS
API Documentation.

User Guide-How to Integrate S2S on EFRIS Version 1.0, EFRIS Project, Process Management Division
Page | 10
 iii. The UAT shall be conducted online after which a certificate of
acceptance shall be signed off by both parties. The taxpayer shall be
issued with a certificate of acceptance to allow him/her set up the
production environment following the same process highlighted step 3
above using the production URLs below;

a) the production portal https://efris.ura.go.ug/

b) Production API URL when connecting directly is;

https://efrisws.ura.go.ug/ws/taapp/getInformation
Please ensure that the version installed is for production and NOT the test
environment.

iv. Register thumbprint and device number on the production by using

Appendix 6.

v. In case the person being tested is a software integrator and not an

individual company integrating their own ERP;
a) the software integrator is required to present 3 companies, for
the UAT.
b) When the 3 companies pass the UATs, in addition to the
certificate of acceptance, the software integrator through
registered email address (where applicable) shall receive a
Certificate of Accreditation for EFRIS Software Integration
signed by the commissioner.
The certificate is issued under Issued under Regulation 5(1) of
the Tax Procedures Code (e-Invoicing and e-Receipting)
Regulation, 2020 and shall be used by the integrator to engage
potential clients for the adoption and implementation of EFRIS.

User Guide-How to Integrate S2S on EFRIS Version 1.0, EFRIS Project, Process Management Division
Page | 11
 c) All accredited Software integrators shall be required to sign an
MOU with URA after paying stamp duty of Ugandan Shillings
15,000per agreement/copy) to onboard their clients on to EFRIS.
d) To onboard the rest of your clients herein referred to as the
taxpayers on EFRIS, as an accredited software integrator, you are
required to install the offline mode enabler (for taxpayers who
have opted to use the offline mode) or setting up the production
environment (for taxpayers using the online mode).

Your client(s) herein referred to as the taxpayer using the email

address registered on the TIN profile are required to submit;
i. A confirmation letter that he/she has appointed you to
complete this integration using your e-invoicing system.
ii. the completed EFRIS Digital Self-Signed Certificate form
(for taxpayers who have opted to use self-signed
certificates) or upload CA signed certificate (for taxpayers
who have opted not to use self-signed certificates) .
Please note:
i. All the three (03) should be submitted at once.
ii. The taxpayer shall receive a notification through the
registered email address when the installation and
configuration process is completed from your side.

iii. The taxpayer will also be able to download the offline mode
enabler for production for Windows, Ubuntu, or CentOS
from the Web portal https://efris.ura.go.ug/ under
downloads>>Applications (Software).

User Guide-How to Integrate S2S on EFRIS Version 1.0, EFRIS Project, Process Management Division
Page | 12
 Appendixes

Appendix 1: Form for Submission of EFRIS Digital Certificate

Appendix 2: Offline-Mode Enabler (For System to System Users) Installation

Guide

Appendix 3
https://efris.ura.go.ug/
Appendix 4: EFRIS System to System Integration UAT Readiness Checklist

EFRIS SYSTEM TO
SYSTEM UAT READINESS CHECKLIST.docx

Appendix 5: How to generate Keys using KeyStore Explorer.

Appendix 6: Step by step guide on system to system integration.

User Guide-How to Integrate S2S on EFRIS Version 1.0, EFRIS Project, Process Management Division
Page | 13