Skip to main content

Goods Stock Records Query (Conditional) (T147)

Query historical stock records filtered by date, supplier, or keywords for the current branch only. This endpoint differs from T145 by restricting results to the authenticated branch context and offering alternative search filters like combineKeywords. Request and response are encrypted.

Endpoint Overview​

PropertyValue
Interface CodeT147
Request Encrypted✅ Yes
Response Encrypted✅ Yes
Request Body{ "combineKeywords": "...", "stockInType": "...", "startDate": "...", "endDate": "...", "pageNo": 1, "pageSize": 10 }
Response FormatJSON with pagination

Flow Description​

  1. Client submits query with optional filters (combineKeywords, stockInType, supplierTin, date range) and pagination parameters.
  2. Server validates the request against the current branch context (authenticated branch).
  3. Server queries stock records matching the criteria for the current branch only.
  4. Server returns paginated results with supplier details, stock-in information, and amounts.
  5. Client displays records or uses data for branch-specific audit/compliance reporting.

💡 Tip: Use T147 instead of T145 when you need to query stock records specifically for the current branch context. T145 queries across all branches.

try {
    // Call T147: Goods Stock Records Query (Conditional/Current Branch)
    $filters = [
        'combineKeywords' => '425502528294126235',  // Optional: referenceNo or supplierName
        'stockInType' => '101',                     // Optional: 101=Import, 102=Local Purchase, etc.
        'startDate' => '2025-02-19',                // Optional: Start date
        'endDate' => '2025-02-19',                  // Optional: End date
        'supplierTin' => '1000029771',              // Optional: Supplier TIN
        'supplierName' => 'UGANDA REVENUE AUTHORITY', // Optional: Supplier Name
        'pageNo' => 1,
        'pageSize' => 10
    ];
    
    $response = $client->queryStockRecordsAlt($filters);
    $content = $response['data']['content'] ?? $response;
    $records = $content['records'] ?? [];
    $page = $content['page'] ?? [];
    
    if (!empty($records)) {
        echo "✅ Retrieved " . count($records) . " stock record(s)\n";
        echo "   Page: {$page['pageNo']}/{$page['pageCount']} (Total: {$page['totalSize']})\n";
        
        foreach ($records as $record) {
            echo "   • Supplier: {$record['supplierName']} (TIN: {$record['supplierTin']})\n";
            echo "     Stock-In Type: {$record['stockInType']}\n";
            echo "     Date: {$record['stockInDate']}\n";
            echo "     Invoice: {$record['invoiceNo']}\n";
            echo "     Amount: {$record['totalAmount']}\n";
            echo "     Branch: {$record['branchName']}\n";
            echo "     ID: {$record['id']}\n";
            echo "\n";
        }
    } else {
        echo "⚠️  No stock records found for provided criteria\n";
    }
    
} catch (\UraEfrisSdk\Exceptions\APIException $e) {
    echo "❌ Query 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": "T147",
    "appId": "AP04",
    "version": "1.1.20191201",
    "tin": "1000029771",
    "deviceNo": "TCS9e0df01728335239",
    "taxpayerID": "1"
  }
}

Request Fields (Encrypted Payload)​

FieldRequiredTypeLengthDescription
combineKeywords❌ NoString≤50Search keyword containing referenceNo or supplierName
stockInType❌ NoString (3)3Filter by stock-in type: 101=Import, 102=Local Purchase, 103=Manufacture/Assembling, 104=Opening Stock
startDate❌ NoDate-Start date for filtering (yyyy-MM-dd)
endDate❌ NoDate-End date for filtering (yyyy-MM-dd)
pageNo✅ YesNumber≤10Current page number (starts from 1)
pageSize✅ YesNumber≤3Records per page; cannot exceed 100
supplierTin❌ NoString≤50Filter by supplier TIN
supplierName❌ NoString≤100Filter by supplier name

💡 Tip: Unlike T145, T147 does not require productionBatchNo, invoiceNo, or referenceNo as mandatory search keys. It uses broader filters scoped to the current branch.

Response Structure​

{
  "data": {
    "content": {
      "page": {
        "pageNo": "1",
        "pageSize": "10",
        "totalSize": "50",
        "pageCount": "5"
      },
      "records": [
        {
          "supplierTin": "1000029771",
          "supplierName": "UGANDA REVENUE AUTHORITY",
          "remarks": "Increase inventory",
          "stockInDate": "2020-09-01",
          "stockInType": "101",
          "productionBatchNo": "1200983",
          "productionDate": "2025-02-19",
          "branchId": "2020090132456",
          "invoiceNo": "320001127399",
          "referenceNo": "425502528294126235",
          "branchName": "PARAMOUR COSMETICS LIMITED",
          "totalAmount": "1000.00",
          "id": "425502528294126235"
        }
      ]
    }
  },
  "globalInfo": {
    "interfaceCode": "T147",
    "returnStateInfo": {
      "returnCode": "00",
      "returnMessage": "SUCCESS"
    }
  }
}

Response Fields​

Pagination Object​

FieldRequiredTypeDescription
pageNo✅ YesNumberCurrent page number
pageSize✅ YesNumberRecords per page
totalSize✅ YesNumberTotal number of matching records
pageCount✅ YesNumberTotal number of pages

Stock Records Array Items​

FieldRequiredTypeLengthDescription
id✅ YesString≤18Unique stock record identifier (use for T148 detail query)
supplierTin❌ NoString≤50Supplier's Taxpayer Identification Number
supplierName❌ NoString≤100Supplier name/business name
remarks❌ NoString≤1024Stock record remarks/notes
stockInDate❌ NoDate-Stock-in date (yyyy-MM-dd)
stockInType❌ NoString (3)3101=Import, 102=Local Purchase, 103=Manufacture/Assembling, 104=Opening Stock
productionBatchNo❌ NoString≤50Production batch number (populated if stockInType=103)
productionDate❌ NoDate-Production date (yyyy-MM-dd; populated if stockInType=103)
branchId❌ NoString≤18Branch identifier (will match current branch context)
branchName❌ NoString≤500Branch name
invoiceNo❌ NoString≤20Associated invoice number
referenceNo❌ NoString≤50Seller's reference number
totalAmount❌ NoNumber-Total stock-in amount

💡 Tip: The id field in the response is required to query full stock record details via T148.

Return Codes​

CodeMessageDescription
00SUCCESSStock records retrieved successfully
99Unknown errorGeneric server error
400Device does not existdeviceNo not registered for this TIN
402Device key expiredDevice credentials expired; re-run T102
403Device status is abnormalDevice blocked or suspended
1521pageNo:cannot be empty!Missing page number in request
1522pageNo:The byte length cannot be less than 0 and cannot be greater than 20!Page number format error
1523pageNo:Cannot be greater than -1!Page number must be positive
1524pageSize:cannot be empty!Missing page size in request
1525pageSize:The byte length cannot be less than 0 and cannot be greater than 3!Page size format error
1526pageSize:Cannot be greater than 100!Page size exceeds maximum (100)
2879combineKeywords: cannot be empty!Keyword search required in some contexts (check validation)
2880combineKeywords: Byte length cannot be greater than 50!Keyword exceeds length limit

💡 Tip: While combineKeywords is marked optional in the field table, error code 2879 suggests it may be required in certain validation contexts. Handle gracefully.

Common Use Cases​

  1. Branch-Specific Stock Auditing
    Query stock records for the current branch only without retrieving data from other branches (unlike T145).

  2. Supplier Transaction Tracking
    Filter records by supplierTin or supplierName to track all stock-ins from a specific supplier for the current branch.

  3. Date-Range Reporting
    Generate stock-in reports for specific periods (e.g., monthly, quarterly) using startDate and endDate.

  4. Keyword Search
    Quickly locate stock records using partial matches on reference numbers or supplier names via combineKeywords.

  5. Stock-In Type Analysis
    Filter by stockInType to analyze import vs. local purchase vs. manufacturing stock flows.

  6. Record Detail Lookup
    Retrieve the id from T147 results to fetch full item-level details via T148.

Integration Checklist​

✅ Ensure pageNo ≥ 1 and pageSize ≤ 100 before submitting request
✅ Handle empty records array gracefully (no matching records found)
✅ Implement pagination logic using pageCount and totalSize from response
✅ Validate date format is yyyy-MM-dd for startDate and endDate
✅ Use T147 for current-branch queries; use T145 for all-branches queries
✅ Cache frequently-queried stock records to reduce API calls
✅ Log query parameters for audit trail compliance
✅ Use response id field to call T148 for detailed item information
✅ Validate stockInType values against T115 dictionary for display purposes
✅ Handle potential 2879 error if combineKeywords validation is enforced