Commodity Category Incremental Update (T134)

Retrieve only the commodity category changes since your local version up to the current server version. This endpoint enables efficient synchronization of tax commodity categories without downloading the entire dictionary. Requires encrypted request and response.

---

Endpoint Overview

Property	Value
Interface Code	T134
Request Encrypted	✅ Yes
Response Encrypted	✅ Yes
Request Body	{ "commodityCategoryVersion": "..." }
Response Format	JSON Array

---

Flow Description

1. Check T103: Sign In response for commodityCategoryVersion.
2. If server version is higher than local version, call T134 with your local version.
3. Loop through the results:
   • If category code exists locally → delete and insert the returned version
   • If category code does not exist → insert into local repository
4. Update your local repository version to match server version.

🔄 Tip: Call this endpoint periodically (e.g., daily) or when T103 indicates a version mismatch to keep your commodity categories up-to-date.

---

PHP

try {
    // Get local version from your database/config
    $localVersion = '1.0';
    
    // Call T134: Commodity Category Incremental Update
    $response = $client->syncCommodityCategories(
        localVersion: $localVersion
    );
    
    $categories = $response['data']['content'] ?? $response;
    
    if (is_array($categories) && count($categories) > 0) {
        echo "✅ Retrieved " . count($categories) . " category updates\n";
        
        foreach ($categories as $category) {
            $code = $category['commodityCategoryCode'] ?? null;
            $name = $category['commodityCategoryName'] ?? null;
            $rate = $category['rate'] ?? null;
            
            // Upsert into local database
            // If exists: DELETE then INSERT
            // If not exists: INSERT
            echo "   - {$code}: {$name} (Rate: {$rate})\n";
        }
        
        // Update local version after successful sync
        // updateLocalVersion($newVersion);
    } else {
        echo "ℹ️  No category updates available\n";
    }
    
} catch (\UraEfrisSdk\Exceptions\APIException $e) {
    echo "❌ Sync failed: " . $e->getMessage() . "\n";
    echo "   Return Code: " . $e->getReturnCode() . "\n";
}

JavaScript / TypeScript

try {
    // Get local version from your database/config
    const localVersion = '1.0';
    
    // Call T134: Commodity Category Incremental Update
    const response = await client.syncCommodityCategories({
        localVersion: localVersion
    });
    
    const categories = response?.data?.content ?? response;
    
    if (Array.isArray(categories) && categories.length > 0) {
        console.log(`✅ Retrieved ${categories.length} category updates`);
        
        categories.forEach((category: any) => {
            const code = category.commodityCategoryCode;
            const name = category.commodityCategoryName;
            const rate = category.rate;
            
            // Upsert into local database
            // If exists: DELETE then INSERT
            // If not exists: INSERT
            console.log(`   - ${code}: ${name} (Rate: ${rate})`);
        });
        
        // Update local version after successful sync
        // await updateLocalVersion(newVersion);
    } else {
        console.log('ℹ️  No category updates available');
    }
    
} catch (error: any) {
    console.error(`❌ Sync failed: ${error.message}`);
    if (error.returnCode) {
        console.error(`   Return Code: ${error.returnCode}`);
    }
    throw error;
}

Python

try:
    # Get local version from your database/config
    local_version = '1.0'
    
    # Call T134: Commodity Category Incremental Update
    response = client.sync_commodity_categories(
        local_version=local_version
    )
    
    categories = response.get("data", {}).get("content", response)
    
    if isinstance(categories, list) and len(categories) > 0:
        print(f"✅ Retrieved {len(categories)} category updates")
        
        for category in categories:
            code = category.get("commodityCategoryCode")
            name = category.get("commodityCategoryName")
            rate = category.get("rate")
            
            # Upsert into local database
            # If exists: DELETE then INSERT
            # If not exists: INSERT
            print(f"   - {code}: {name} (Rate: {rate})")
        
        # Update local version after successful sync
        # update_local_version(new_version)
    else:
        print("ℹ️  No category updates available")
    
except Exception as e:
    print(f"❌ Sync failed: {e}")
    if hasattr(e, "return_code"):
        print(f"   Return Code: {e.return_code}")
    raise

---

Request Structure

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

Request Fields (Encrypted Payload)

Field	Required	Type	Description
commodityCategoryVersion	✅ Yes	String	Your local commodity category version (e.g., "1.0")

---

Response Structure

{
  "data": {
    "content": [
      {
        "commodityCategoryCode": "100000000",
        "parentCode": "0",
        "commodityCategoryName": "Standard",
        "commodityCategoryLevel": "1",
        "rate": "0.18",
        "isLeafNode": "101",
        "serviceMark": "101",
        "isZeroRate": "101",
        "zeroRateStartDate": "19/02/2025",
        "zeroRateEndDate": "28/02/2025",
        "isExempt": "101",
        "exemptRateStartDate": "19/02/2025",
        "exemptRateEndDate": "28/02/2025",
        "enableStatusCode": "1",
        "exclusion": "1",
        "excisable": "101",
        "vatOutScopeCode": "102"
      }
    ]
  },
  "globalInfo": {
    "interfaceCode": "T134",
    "returnStateInfo": {
      "returnCode": "00",
      "returnMessage": "SUCCESS"
    }
  }
}

---

Response Fields

Field	Required	Type	Description
commodityCategoryCode	✅ Yes	String (18)	Unique commodity category identifier
parentCode	✅ Yes	String (18)	Parent category code (0 for root level)
commodityCategoryName	✅ Yes	String (200)	Category name (e.g., "Standard", "Exempt")
commodityCategoryLevel	✅ Yes	String (1)	Hierarchy level (1=root, 2=child, etc.)
rate	✅ Yes	String (4)	Tax rate (e.g., "0.18" for 18%)
isLeafNode	✅ Yes	String (3)	101=Yes (no children), 102=No (has children)
serviceMark	✅ Yes	String (3)	101=Service, 102=Goods
isZeroRate	✅ Yes	String (3)	101=Zero-rated, 102=Not zero-rated
zeroRateStartDate	❌ No	Date	Zero-rate effective start date (dd/MM/yyyy)
zeroRateEndDate	❌ No	Date	Zero-rate effective end date (dd/MM/yyyy)
isExempt	✅ Yes	String (3)	101=Exempt, 102=Not exempt
exemptRateStartDate	❌ No	Date	Exemption effective start date (dd/MM/yyyy)
exemptRateEndDate	❌ No	Date	Exemption effective end date (dd/MM/yyyy)
enableStatusCode	✅ Yes	String (1)	1=Enabled, 0=Disabled
exclusion	✅ Yes	String (1)	0=Zero, 1=Exempt, 2=No exclusion, 3=Both
excisable	✅ Yes	String (3)	101=Excisable, 102=Not excisable
vatOutScopeCode	✅ Yes	String (3)	101=VAT Out of Scope, 102=Not out of scope

---

Return Codes

Code	Message	Description
00	SUCCESS	Incremental update retrieved successfully
99	Unknown error	Generic server error
400	Device does not exist	deviceNo not registered
402	Device key expired	Device credentials expired; re-run T102
403	Device status is abnormal	Device blocked or suspended
2059	commodityCategoryVersion cannot be empty	Missing version parameter

💡 Tip: An empty array response ([]) with return code 00 means your local version is already up-to-date—no changes since your specified version.

---

Common Use Cases

1. Daily Synchronization
   Schedule T134 calls during off-peak hours to keep commodity categories current without full dictionary downloads.

2. Version Mismatch Handling
   When T103 returns a higher commodityCategoryVersion, immediately call T134 to fetch only the changes.

3. Multi-Branch Consistency
   Ensure all branches use the same commodity category versions by syncing from a central server.

4. Audit Trail Maintenance
   Log category changes (additions, modifications, deletions) for compliance and troubleshooting.

5. Offline Mode Preparation
   Cache the latest categories before going offline to ensure accurate tax calculations without server access.

---

Integration Checklist

✅ Store local commodityCategoryVersion in your database
✅ Compare with T103 response before calling T134
✅ Handle empty array response as "no changes" (success)
✅ Upsert categories: DELETE existing + INSERT new for updates
✅ Update local version only after successful sync
✅ Log category changes for audit purposes