Skip to main content

Goods Stock Adjust Records Query (T149)

Query historical stock adjustment records with pagination support. This endpoint returns stock adjustment records including adjustment types, dates, amounts, and branch information for audit and compliance purposes. Request and response are encrypted.

Endpoint Overview​

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

Flow Description​

  1. Client submits query with optional filters (referenceNo, startDate, endDate) and pagination parameters.
  2. Server validates the request parameters and date range.
  3. Server queries stock adjustment records matching the criteria across all branches.
  4. Server returns paginated results with adjustment details including type, date, amount, and remarks.
  5. Client displays records or uses data for audit/compliance reporting.

💡 Tip: Use T149 to query stock adjustment records (different from T145/T147 which query stock-in records). Use the id from response to call T160 for detailed item-level information.

try {
    // Call T149: Goods Stock Adjust Records Query
    $filters = [
        'referenceNo' => '425502528294126235',  // Optional: reference number
        'startDate' => '2025-02-19',             // Optional: Start date
        'endDate' => '2025-02-20',               // Optional: End date
        'pageNo' => 1,
        'pageSize' => 10
    ];
    
    $response = $client->queryStockAdjustRecords($filters);
    $content = $response['data']['content'] ?? $response;
    $records = $content['records'] ?? [];
    $page = $content['page'] ?? [];
    
    if (!empty($records)) {
        echo "✅ Retrieved " . count($records) . " adjustment record(s)\n";
        echo "   Page: {$page['pageNo']}/{$page['pageCount']} (Total: {$page['totalSize']})\n";
        
        foreach ($records as $record) {
            echo "   • Branch: {$record['branchName']}\n";
            echo "     Adjust Date: {$record['adjustDate']}\n";
            echo "     Adjust Type: {$record['adjustType']}\n";
            echo "     Amount: {$record['adjustAmount']}\n";
            echo "     Reference: {$record['referenceNo']}\n";
            echo "     Remarks: {$record['remarks']}\n";
            echo "     ID: {$record['id']}\n";
            echo "\n";
        }
    } else {
        echo "⚠️  No stock adjustment 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": "T149",
    "appId": "AP04",
    "version": "1.1.20191201",
    "tin": "1000029771",
    "deviceNo": "TCS9e0df01728335239",
    "taxpayerID": "1"
  }
}

Request Fields (Encrypted Payload)​

FieldRequiredTypeLengthDescription
referenceNo❌ NoString≤50Reference number for filtering adjustment records
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

💡 Tip: All filter fields (referenceNo, startDate, endDate) are optional. If omitted, the query returns all adjustment records within pagination limits.

Response Structure​

{
  "data": {
    "content": {
      "page": {
        "pageNo": "1",
        "pageSize": "10",
        "totalSize": "50",
        "pageCount": "5"
      },
      "records": [
        {
          "id": "208178192251887451",
          "referenceNo": "425502528294126235",
          "branchName": "PARAMOUR COSMETICS LIMITED",
          "adjustDate": "2025-02-19",
          "adjustType": "101",
          "remarks": "Increase inventory",
          "adjustAmount": "500.00"
        }
      ]
    }
  },
  "globalInfo": {
    "interfaceCode": "T149",
    "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 Adjust Records Array Items​

FieldRequiredTypeLengthDescription
id✅ YesString≤18Unique adjustment record identifier (use for T160 detail query)
referenceNo❌ NoString≤50Reference number associated with the adjustment
branchName❌ NoString≤500Branch name where adjustment occurred
adjustDate❌ NoDate-Adjustment date (yyyy-MM-dd)
adjustType❌ NoString (3)3101=Expired Goods, 102=Damaged Goods, 103=Personal Uses, 104=Others, 105=Raw Material(s)
remarks❌ NoString≤1024Adjustment remarks/notes
adjustAmount❌ NoNumber-Total adjustment amount (integer ≤12 digits, decimal ≤8 digits)

💡 Tip: Use the id field from the response to call T160 (Goods Stock Adjust Detail Query) for item-level details of a specific adjustment record.

Return Codes​

CodeMessageDescription
00SUCCESSStock adjustment 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
2880combineKeywords: Byte length cannot be greater than 50!Keyword exceeds length limit

💡 Tip: Error codes 1521-1526 are the most common pagination-related errors. Ensure pageNo ≥ 1 and pageSize ≤ 100.

Common Use Cases​

  1. Stock Adjustment Auditing
    Query historical stock adjustment records for compliance audits and financial reconciliation.

  2. Adjustment Type Analysis
    Filter records by adjustType to analyze patterns (expired goods, damaged goods, personal uses, etc.).

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

  4. Reference Number Lookup
    Locate adjustment records using reference numbers for transaction tracking and verification.

  5. Branch-Specific Analysis
    Analyze adjustment patterns across branches using branchName from record details.

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

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 T149 for adjustment records; use T145/T147 for stock-in records
✅ Cache frequently-queried adjustment records to reduce API calls
✅ Log query parameters for audit trail compliance
✅ Use response id field to call T160 for detailed item information
✅ Validate adjustType values against T115 dictionary for display purposes
✅ Handle potential 2879 error if keyword validation is enforced