Get All Branches (T138)

Retrieve all registered branches for the authenticated taxpayer. This endpoint returns branch identifiers and names, enabling multi-branch operations such as stock transfers, branch-specific invoicing, and agent management. Request is unencrypted; response is encrypted.

Endpoint Overview

Property	Value
Interface Code	`T138`
Request Encrypted	❌ No
Response Encrypted	✅ Yes
Request Body	`null` (empty)
Response Format	JSON Array

Flow Description

Client calls T138 with no request payload (authentication via globalInfo).
Server validates the authenticated taxpayer (tin in globalInfo).
Server queries all branches registered under the taxpayer's TIN.
Server returns an array of branch objects containing branchId and branchName.
Client stores branch IDs for use in subsequent operations (e.g., T131 stock maintain, T139 stock transfer, T109 invoicing).

💡 Tip: Call T138 after successful sign-in (T103) to populate your branch selector UI. Store the branchId for branch-specific API calls.

PHP
JavaScript / TypeScript
Python

try {
    // Call T138: Get All Branches
    $response = $client->getRegisteredBranches();
    
    $content = $response['data']['content'] ?? $response;
    
    if (is_array($content) && count($content) > 0) {
        echo "✅ Retrieved " . count($content) . " branch(es)\n";
        
        foreach ($content as $branch) {
            echo "   • {$branch['branchName']} (ID: {$branch['branchId']})\n";
        }
        
        // Store first branch for subsequent operations
        $firstBranchId = $content[0]['branchId'] ?? null;
        echo "   → Using branch ID: {$firstBranchId}\n";
        
    } else {
        echo "⚠️  No branches found for this taxpayer\n";
    }
    
} catch (\UraEfrisSdk\Exceptions\APIException $e) {
    echo "❌ Failed to retrieve branches: " . $e->getMessage() . "\n";
    echo "   Return Code: " . $e->getReturnCode() . "\n";
}

try {
    // Call T138: Get All Branches
    const response = await client.getRegisteredBranches();
    
    const content = response?.data?.content ?? response;
    
    if (Array.isArray(content) && content.length > 0) {
        console.log(`✅ Retrieved ${content.length} branch(es)`);
        
        content.forEach((branch: any) => {
            console.log(`   • ${branch.branchName} (ID: ${branch.branchId})`);
        });
        
        // Store first branch for subsequent operations
        const firstBranchId = content[0]?.branchId ?? null;
        console.log(`   → Using branch ID: ${firstBranchId}`);
        
        return content;
    } else {
        console.warn('⚠️  No branches found for this taxpayer');
        return [];
    }
    
} catch (error: any) {
    console.error(`❌ Failed to retrieve branches: ${error.message}`);
    if (error.returnCode) {
        console.error(`   Return Code: ${error.returnCode}`);
    }
    throw error;
}

try:
    # Call T138: Get All Branches
    response = client.get_registered_branches()
    
    content = response.get("data", {}).get("content", response)
    
    if isinstance(content, list) and len(content) > 0:
        print(f"✅ Retrieved {len(content)} branch(es)")
        
        for branch in content:
            print(f"   • {branch['branchName']} (ID: {branch['branchId']})")
        
        # Store first branch for subsequent operations
        first_branch_id = content[0].get("branchId") if content else None
        print(f"   → Using branch ID: {first_branch_id}")
        
    else:
        print("⚠️  No branches found for this taxpayer")
    
except Exception as e:
    print(f"❌ Failed to retrieve branches: {e}")
    if hasattr(e, "return_code"):
        print(f"   Return Code: {e.return_code}")
    raise

Request Structure

{
  "data": {
    "content": "",
    "signature": "",
    "dataDescription": {
      "codeType": "0",
      "encryptCode": "0",
      "zipCode": "0"
    }
  },
  "globalInfo": {
    "interfaceCode": "T138",
    "appId": "AP04",
    "version": "1.1.20191201",
    "tin": "1000029771",
    "deviceNo": "TCS9e0df01728335239",
    "taxpayerID": "1",
    "requestTime": "2025-02-19 10:00:00"
  }
}

Request Fields

📋 Note: T138 requires no encrypted payload. All authentication is handled via globalInfo headers.

Field (globalInfo)	Required	Type	Description
`tin`	✅ Yes	String (≤20)	Taxpayer Identification Number (from sign-in)
`deviceNo`	✅ Yes	String (≤20)	Registered device serial number
`interfaceCode`	✅ Yes	String (5)	Must be `"T138"`
`requestTime`	✅ Yes	String	Timestamp format: `yyyy-MM-dd HH:mm:ss`

Response Structure

{
  "data": {
    "content": [
      {
        "branchId": "206637525568955296",
        "branchName": "Mr. STEPHEN BUNJO"
      },
      {
        "branchId": "206637528324276772",
        "branchName": "ARINAIT AND SONS CO. LIMITED"
      }
    ]
  },
  "globalInfo": {
    "interfaceCode": "T138",
    "returnStateInfo": {
      "returnCode": "00",
      "returnMessage": "SUCCESS"
    }
  }
}

Response Fields

Branch Array Items

Field	Required	Type	Length	Description
`branchId`	✅ Yes	String	≤18	Unique branch identifier (used in T131, T139, T109, etc.)
`branchName`	✅ Yes	String	≤500	Human-readable branch name/display name

💡 Tip: The branchId is required for branch-specific operations. Always validate that the branch belongs to the current taxpayer before use.

Return Codes

Code	Message	Description
`00`	SUCCESS	Branches retrieved successfully
`99`	Unknown error	Generic server error
`100`	Taxpayer does not exist	TIN not found in system
`101`	Taxpayer status is abnormal	TIN suspended, deregistered, or inactive
`102`	Taxpayer branch status abnormal	One or more branches have invalid status
`400`	Device does not exist	`deviceNo` not registered for this TIN
`402`	Device key expired	Device credentials expired; re-run T102
`403`	Device status is abnormal	Device blocked or suspended
`2189`	branchName:cannot be empty!	Internal validation error
`2190`	branchName:Byte length cannot be greater than 500!	Branch name exceeds limit

💡 Tip: An empty array ([]) in the response content indicates the taxpayer has no registered branches—this is valid for single-location taxpayers.

Common Use Cases

Branch Selection UI
Populate dropdown menus or branch selectors in your application interface after user sign-in.
Stock Transfer Operations (T139)
Retrieve valid sourceBranchId and destinationBranchId values for inter-branch stock transfers.
Branch-Specific Invoicing (T109)
Include branchId in sellerDetails when issuing invoices from a specific branch location.
Stock Management (T131)
Specify the target branchId when maintaining stock levels for branch-specific inventory.
Agent/Principal Validation
Verify branch relationships when managing agent invoicing or principal-agent workflows.
Multi-Tenant Applications
Support taxpayers with multiple branches by storing and switching between branchId values session-wide.

Integration Checklist

✅ Call T138 immediately after successful T103 sign-in
✅ Validate response is an array before iterating
✅ Store branchId values in session/cache for subsequent API calls
✅ Handle empty array response (single-location taxpayer) gracefully
✅ Use branchName for display; always use branchId for API requests
✅ Re-fetch branches periodically if taxpayer branch configuration may change
✅ Validate that selected branchId exists in the returned list before use
✅ Log branch selection events for audit trails in multi-branch environments

Endpoint Overview​

Flow Description​

Request Structure​

Request Fields​

Response Structure​

Response Fields​

Branch Array Items​

Return Codes​

Common Use Cases​

Integration Checklist​