Requirements

Before integrating with the URA EFRIS System-to-System API using the community-maintained SDKs (PHP, JavaScript, or Python), ensure that all technical, regulatory, and environment requirements below are met.

Failure to meet these requirements will result in authentication errors, rejected payloads, signature validation failures, or failed URA audits.

1. URA Prerequisites (Mandatory)

EFRIS System-to-System Registration

You must be approved by URA to integrate using the System-to-System (S2S) flow.

Your business must be registered on the EFRIS Portal
S2S credentials must be issued by URA (distinct from EFD/AskURA credentials)
Sandbox credentials are different from production credentials

⚠️ These SDKs are S2S-only (appId: "AP04"). They will not work with EFD device-based or AskURA (appId: "AP05") integrations.

Required URA Credentials

You will receive the following from URA:

Variable	Description
`tin`	Taxpayer Identification Number (10–20 digits)
`deviceNo`	Device Serial Number (DSN) – virtual or physical
`taxpayerId`	Taxpayer internal ID (usually `1`)
`brn`	Business Registration Number (optional, if applicable)
`pfxPath`	Path to your `.pfx` certificate file
`pfxPassword`	Password for the PFX certificate
`env`	Environment: `sbx` (sandbox) or `prod` (production)

2. Supported Environments

All SDKs support both sandbox and production environments.

Environment	Base URL	Purpose
Sandbox	`https://efristest.ura.go.ug/efrisws/ws/taapp/getInformation`	Development & testing
Production	`https://efrisws.ura.go.ug/ws/taapp/getInformation`	Live URA submissions

⚠️ Sandbox behavior may differ slightly from production (e.g., relaxed TIN validation), but payload validation rules, encryption requirements, and ReturnCode logic are identical.

3. Language-Specific Requirements

PHP
JavaScript / Typescript
Python

PHP

PHP 8.1+
Extensions:
- curl
- json
- openssl (for RSA/AES encryption)
- mbstring (for UTF-8 handling)
Composer (Packagist)

php -v
composer -V

JavaScript / Typescript

Node.js 18+
npm (NPM) or yarn
crypto module support (built-in)
HTTPS support enabled

node -v
npm -v

Python

Python 3.9+
pip package manager (PyPI)
cryptography library for RSA/AES operations
Virtual environment recommended

python --version
pip --version

4. System & Network Requirements

Outbound HTTPS access to:
- https://efristest.ura.go.ug/efrisws/ws/taapp/getInformation
- https://efrisws.ura.go.ug/ws/taapp/getInformation
TLS 1.2 or higher
Valid system clock (time drift >10 minutes causes ReturnCode: 28)
Ability to read .pfx certificate files with provided password

⏱️ Time synchronization is critical. Request timestamps (requestTime) must be within ±10 minutes of URA server time. Use T101: Get Server Time to sync clocks before initialization.

5. Payload & Date Rules (Critical)

JSON Envelope Structure

All requests/responses follow this outer-layer format:

{
  "data": {
    "content": "BASE64-encoded (encrypted) payload",
    "signature": "JKQWJK34K32JJEK2JQWJ5678",
    "dataDescription": {
      "codeType": "1",
      "encryptCode": "1",
      "zipCode": "0"
    }
  },
  "globalInfo": {
    "appId": "AP04",
    "version": "1.1.20191201",
    "dataExchangeId": "9230489223014123",
    "interfaceCode": "T109",
    "requestCode": "TP",
    "requestTime": "2026-02-25 14:30:22",
    "responseCode": "TA",
    "userName": "admin",
    "deviceMAC": "FFFFFFFFFFFF",
    "deviceNo": "TCS9e0df01728335239",
    "tin": "1000029771",
    "brn": "",
    "taxpayerID": "1",
    "longitude": "32.5825",
    "latitude": "0.3476",
    "agentType": "0"
  },
  "returnStateInfo": {
    "returnCode": "",
    "returnMessage": ""
  }
}

Date & Time Formats

Context	Format	Example	Notes
Request timestamps (`requestTime`, `issuedDate`)	`yyyy-MM-dd HH:mm:ss`	`2026-02-25 14:30:22`	Must be Uganda time
Response timestamps (`currentTime`, `issuedDate` in responses)	`dd/MM/yyyy HH:mm:ss`	`25/02/2026 14:30:22`	Follows `extendField.responseTimeFormat`
Stock dates (`stockInDate`, `productionDate`)	`yyyy-MM-dd`	`2026-02-25`	Date only

📅 Critical Rules:

issuedDate cannot be in the future

Back-dating invoices is only allowed if isAllowBackDate: "1" in T103 response

lastReqDt equivalent fields must not exceed URA retention policies

Invoice Numbering

Invoice numbers (invoiceNo) are assigned by URA upon successful upload (T109)
Your system must track the referenceNo (seller's transaction reference) for reconciliation
referenceNo must be unique per taxpayer and ≤50 characters

// ✅ Correct: Let URA assign invoiceNo
'basicInformation' => [
    'invoiceNo' => '', // Leave empty in request
    'referenceNo' => 'TXN_' . time() . '_' . uniqid()
]

// ❌ Rejected: Supplying your own invoiceNo
'basicInformation' => [
    'invoiceNo' => 'INV-2026-001' // Will be ignored or cause error
]

6. Encryption & Signature Requirements

All S2S integrations must implement:

Step	Interface	Purpose
1	`T102: Client Initialization`	Obtain RSA key pair (`clientPriKey`, `serverPubKey`, `keyTable`)
2	`T103: Sign In`	Authenticate and receive taxpayer/branch/device metadata
3	`T104: Get Symmetric Key`	Obtain AES key (`passowrdDes`) and signature value for subsequent requests
4	All subsequent calls	Encrypt `content` with AES, sign with RSA, BASE64-encode

🔐 Encryption Flow:

Serialize inner payload to JSON

Compress (if zipCode: "1")

Encrypt with AES symmetric key

BASE64-encode → data.content

Sign the encrypted content with RSA private key → data.signature

Wrap in outer JSON envelope with globalInfo

The SDKs handle this automatically—do not attempt manual encryption unless extending the SDK.

7. Validation Behavior

All SDKs perform local validation before sending requests to URA:

Required fields per interface code (T109, T110, etc.) are enforced
Data types, lengths, and enumerated values are validated
Business rules (e.g., discountFlag sequencing, excise duty consistency) are checked early
ReturnCode mappings are translated to human-readable errors

This reduces failed submissions and simplifies debugging.

8. Security Best Practices

Store credentials in environment variables or secure vaults—never in source code
Restrict file permissions on .pfx certificates and key cache files
Rotate PFX certificates and device credentials when staff or systems change
Log URA responses securely—mask content, signature, and credential fields
Monitor returnCode values and implement retry logic for transient errors (99, 46, 9901, 9902)

9. Compliance & Audit Considerations

Maintain local copies of all submitted invoices and URA acknowledgments
Reconcile referenceNo and invoiceNo mappings daily
Implement idempotency for invoice uploads to avoid duplicates
Handle T117: Invoice Checks for periodic reconciliation with URA records
Retain audit logs for ≥7 years per URA regulations

1. URA Prerequisites (Mandatory)​

EFRIS System-to-System Registration​

Required URA Credentials​

2. Supported Environments​

3. Language-Specific Requirements​

PHP​

JavaScript / Typescript​

Python​

4. System & Network Requirements​

5. Payload & Date Rules (Critical)​

JSON Envelope Structure​

Date & Time Formats​

Invoice Numbering​

6. Encryption & Signature Requirements​

7. Validation Behavior​

8. Security Best Practices​

9. Compliance & Audit Considerations​