Skip to main content

TCS Upgrade Download (T133)

Retrieve system upgrade files, commands, and SQL scripts required to update the Tax Control System (TCS) software. This endpoint provides the necessary artifacts (binaries, configurations, database scripts) based on the current version and operating system. Requires encrypted request and response.

Endpoint Overview​

PropertyValue
Interface CodeT133
Request Encrypted✅ Yes
Response Encrypted✅ Yes
Request Body{ "tcsVersion": "...", "osType": "..." }
Response FormatJSON (with file URLs and scripts)

Flow Description​

  1. Client checks current TCS version (via T135 or local config).
  2. Client requests upgrade files for target version and OS (Linux/Windows).
  3. Server returns:
    • Pre-command scripts (Base64 encoded).
    • Main command scripts (Base64 encoded).
    • List of files to update/download (URLs).
    • List of SQL scripts to execute (Base64 encoded).
  4. Client downloads files from provided URLs and executes scripts in specified order.

⚠️ Critical: Execute commands and SQL scripts in the ordernumber sequence provided to ensure system integrity.

try {
    // Call T133: TCS Upgrade Download
    $response = $client->tcsUpgradeDownload(
        tcsVersion: '2',      // Target version number
        osType: '1'           // 0=Linux, 1=Windows
    );
    
    $content = $response['data']['content'] ?? $response;
    
    if (isset($content['fileList'], $content['sqlList'])) {
        echo "✅ Upgrade package retrieved\n";
        echo "   Version: {$content['tcsversion']}\n";
        echo "   Files to update: " . count($content['fileList']) . "\n";
        echo "   SQL scripts: " . count($content['sqlList']) . "\n";
        
        // Process files in order
        foreach ($content['fileList'] as $file) {
            echo "   - Download: {$file['updateurl']}\n";
            echo "     Order: {$file['ordernumber']}\n";
        }
    } else {
        echo "⚠️  No upgrade files found\n";
    }
    
} catch (\UraEfrisSdk\Exceptions\APIException $e) {
    echo "❌ Upgrade download failed: " . $e->getMessage() . "\n";
    echo "   Return Code: " . $e->getReturnCode() . "\n";
}

Request Structure​

{
  "data": {
    "content": "BASE64_ENCRYPTED_PAYLOAD",
    "signature": "JKQWJK34K32JJEK2JQWJ5678",
    "dataDescription": {
      "codeType": "1",
      "encryptCode": "2",
      "zipCode": "0"
    }
  },
  "globalInfo": {
    "interfaceCode": "T133",
    "appId": "AP04",
    "version": "1.1.20191201",
    "tin": "1000029771",
    "deviceNo": "TCS9e0df01728335239",
    "taxpayerID": "1"
  }
}

Request Fields (Encrypted Payload)​

FieldRequiredTypeDescription
tcsVersion✅ YesNumberTarget TCS version number (starts from 1)
osType✅ YesString (1)Operating system: 0=Linux, 1=Windows

Response Structure​

{
  "data": {
    "content": {
      "precommand": "BASE64_SCRIPT_CONTENT",
      "precommandurl": "./jmeter/bin",
      "precommandfilename": "abc.txt",
      "command": "BASE64_SCRIPT_CONTENT",
      "commandurl": "./home/tomcat",
      "commandfilename": "a.docx",
      "tcsversion": "2",
      "fileList": [
        {
          "updatefile": "BASE64_FILE_CONTENT",
          "iszip": "1",
          "updateurl": "https://efris.ura.go.ug/uploads/file.zip",
          "deleteurl": "/ad/fsads",
          "ordernumber": "1"
        }
      ],
      "sqlList": [
        {
          "updatesql": "BASE64_SQL_CONTENT",
          "ordernumer": "3"
        }
      ]
    }
  },
  "globalInfo": {
    "interfaceCode": "T133",
    "returnStateInfo": {
      "returnCode": "00",
      "returnMessage": "SUCCESS"
    }
  }
}

Response Fields​

FieldRequiredTypeDescription
precommand✅ YesString (Base64)Pre-command script content (Base64 encoded)
precommandurl✅ YesString (256)Path/URL for pre-command execution
precommandfilename❌ NoString (500)Filename for pre-command script
command✅ YesString (Base64)Main command script content (Base64 encoded)
commandurl✅ YesString (256)Path/URL for command execution
commandfilename❌ NoString (500)Filename for main command script
tcsversion✅ YesStringTarget TCS version number
fileList✅ YesArrayList of files to update/download
sqlList✅ YesArrayList of SQL scripts to execute

fileList Array Fields​

FieldRequiredTypeDescription
updatefile✅ YesString (Base64)File content (Base64 encoded) or placeholder
iszip❌ NoString1=Zipped, 0=Unzipped
updateurl✅ YesString (256)URL to download the update file
deleteurl✅ YesString (256)URL/path for cleanup/deletion
ordernumber✅ YesString (10)Execution sequence number

sqlList Array Fields​

FieldRequiredTypeDescription
updatesql✅ YesString (Base64)SQL script content (Base64 encoded)
ordernumer✅ YesString (10)Execution sequence number (note: API spec uses ordernumer)

Return Codes​

CodeMessageDescription
00SUCCESSUpgrade package retrieved successfully
99Unknown errorGeneric server error
47The current version does not support incremental upgradeCurrent version cannot be upgraded incrementally; full install required
400Device does not existdeviceNo not registered
402Device key expiredDevice credentials expired
403Device status is abnormalDevice blocked or suspended

💡 Tip: If you receive code 47, contact URA support for a full installation package instead of an incremental upgrade.

Common Use Cases​

  1. Automated System Updates
    Integrate into your application's update checker to automatically download and apply TCS patches.

  2. Version Compliance
    Ensure your TCS software matches the latest version required by URA for continued operation.

  3. Database Schema Migration
    Execute provided SQL scripts (sqlList) to update local database schemas to match new version requirements.

  4. Multi-OS Deployment
    Request appropriate files for Linux (osType=0) or Windows (osType=1) environments.

Integration Checklist​

✅ Check current version before calling (use T135)
✅ Verify osType matches your server environment
✅ Execute precommand before main command
✅ Process fileList and sqlList in ordernumber sequence
✅ Validate Base64 decoding for scripts and files
✅ Log upgrade actions for audit trails