Skip to main content

Configuration

Before using the URA EFRIS System-to-System SDKs, you must configure your environment variables and SDK bootstrap settings. This ensures proper authentication, key exchange, encryption, and API usage.


PHP SDK Configuration​

Load environment variables and bootstrap the SDK:

use UraEfrisSdk\Client;
use UraEfrisSdk\KeyClient;
use Dotenv\Dotenv;

// Load env variables using dotenv if needed
$dotenv = Dotenv::createImmutable(__DIR__);
$dotenv->load();

// SDK Config
$config = [
'env' => getenv('EFRIS_ENV') ?: 'sbx',
'tin' => getenv('EFRIS_TIN'),
'device_no' => getenv('EFRIS_DEVICE_NO'),
'brn' => getenv('EFRIS_BRN') ?: '',
'taxpayer_id' => getenv('EFRIS_TAXPAYER_ID') ?: '1',
'pfx_path' => getenv('EFRIS_PFX_PATH'),
'pfx_password' => getenv('EFRIS_PFX_PASSWORD'),
'http' => [
'timeout' => (int) (getenv('EFRIS_HTTP_TIMEOUT') ?: 120)
]
];

// Initialize KeyClient (handles RSA/AES encryption)
$keyClient = new KeyClient(
pfxPath: $config['pfx_path'],
password: $config['pfx_password'],
tin: $config['tin'],
deviceNo: $config['device_no'],
brn: $config['brn'],
sandbox: $config['env'] === 'sbx',
timeout: $config['http']['timeout'],
taxpayerId: $config['taxpayer_id']
);

// Initialize main Client
$client = new Client(config: $config, keyClient: $keyClient);

// Optional: Run initialization flow on first run
// $client->clientInit(); // T102 - Get RSA keys
// $client->signIn(); // T103 - Authenticate & get metadata
// $client->getSymmetricKey(); // T104 - Get AES key for subsequent calls

Environment Variables Reference​

VariableDescriptionExampleRequired
EFRIS_ENVEnvironment: sbx or prodsbx✅
EFRIS_TINTaxpayer Identification Number1000029771✅
EFRIS_DEVICE_NODevice Serial Number (DSN)TCS9e0df01728335239✅
EFRIS_BRNBusiness Registration NumberBRN123456❌
EFRIS_TAXPAYER_IDTaxpayer internal ID (usually 1)1❌
EFRIS_PFX_PATHPath to .pfx certificate file/secure/certs/ura.pfx✅
EFRIS_PFX_PASSWORDPassword for the PFX certificate••••••••✅
EFRIS_HTTP_TIMEOUTHTTP request timeout in seconds120❌
EFRIS_LOG_LEVELLogging level: debug | info | warn | errorinfo❌

Sample .env File​

# Environment
EFRIS_ENV=sbx

# Taxpayer Credentials
EFRIS_TIN=1000029771
EFRIS_DEVICE_NO=TCS9e0df01728335239
EFRIS_BRN=
EFRIS_TAXPAYER_ID=1

# Certificate
EFRIS_PFX_PATH=/path/to/secure/ura.pfx
EFRIS_PFX_PASSWORD=your_secure_password

# Network
EFRIS_HTTP_TIMEOUT=120

# Logging (JS/TS only)
EFRIS_LOG_LEVEL=info

Step-by-Step Breakdown​

StepInterfacePurposeKey Outputs
1T101: Get Server TimeSynchronize client clock with URA servercurrentTime (dd/MM/yyyy HH:mm:ss)
2T102: Client InitializationExchange RSA keys with URAclientPriKey, serverPubKey, keyTable
3T103: Sign InAuthenticate taxpayer & retrieve metadataTaxpayer info, branch list, feature flags, dictionaryVersion
4T104: Get Symmetric KeyObtain AES key for payload encryptionpassowrdDes, sign

💡 Tip: The SDK handles this flow automatically on the first API call. You only need to run it manually if you want to pre-warm keys or handle initialization errors explicitly.


Certificate & Key Management​

PFX Certificate Requirements​

RequirementSpecification
FormatPKCS#12 (.pfx or .p12)
Key SizeRSA 2048-bit minimum
ContentsMust contain both private key and public certificate
ProtectionPassword-protected (use strong passwords)
ValidityMust not be expired; renew before expiration

Key Rotation Procedure​

  1. Generate new PFX certificate via URA portal or contact URA support
  2. Update EFRIS_PFX_PATH and EFRIS_PFX_PASSWORD in your environment
  3. Restart your application to reload credentials
  4. Re-run initialization flow (T102 → T103 → T104)
  5. Verify API calls succeed with new credentials

Security Best Practices​

PracticeImplementation
🔐 Protect certificatesStore .pfx files in encrypted storage or HSM; never in source control
🔑 Restrict file permissionschmod 600 /path/to/cert.pfx; use OS-level access controls
🚫 Avoid logging sensitive dataMask content, signature, clientPriKey, passowrdDes in logs
🔄 Rotate credentials regularlyUpdate PFX certificates and device credentials on staff/system changes
🧪 Test in sandbox firstAlways validate initialization and API flows in sbx before prod
📋 Maintain audit logsLog all API requests/responses with masked sensitive fields for compliance
⏰ Monitor clock driftAlert if time synchronization exceeds ±5 minutes to prevent ReturnCode: 28
🛡️ Validate inputs earlyUse SDK's built-in validation to catch errors before network calls

Troubleshooting Common Configuration Issues​

SymptomLikely CauseSolution
ReturnCode: 28Clock drift >10 minutesSync system time; call T101 before initialization
ReturnCode: 400Invalid or missing deviceNoVerify EFRIS_DEVICE_NO matches URA registration
ReturnCode: 401Missing or expired device keysRe-run T102: Client Initialization
ReturnCode: 100Invalid or unregistered tinConfirm TIN is active in URA system
EncryptionExceptionInvalid PFX password or corrupt certificateVerify EFRIS_PFX_PASSWORD; regenerate certificate if needed
ValidationExceptionMissing required fields in payloadUse SDK methods; avoid manual JSON construction
Connection timeoutNetwork/firewall blocking URA endpointsAllow outbound HTTPS to efrisws.ura.go.ug and efristest.ura.go.ug