Skip to main content

Goods/Services Inquiry by Goods Code (T144)

Batch query goods or services by their registered goods codes. This endpoint returns unit of measure configurations, scaling values, and alternative unit mappings for enabled goods. Request and response are encrypted.

Endpoint Overview​

PropertyValue
Interface CodeT144
Request Encrypted✅ Yes
Response Encrypted✅ Yes
Request Body{ "goodsCode": "0001,0002", "tin": "..." }
Response FormatJSON Array

Flow Description​

  1. Client submits one or more goodsCode values (comma-separated) and optional principal tin for agent queries.
  2. Server validates goods codes against registered goods with statusCode = 101 (enabled).
  3. Server returns configuration details for each matched goods:
    • Primary unit of measure (measureUnit)
    • Piece unit configuration (havePieceUnit, pieceMeasureUnit, scaling values)
    • Alternative unit mappings (haveOtherUnit, goodsOtherUnits array)
  4. Client uses response to populate unit selectors, calculate conversions, or validate invoice line items.

💡 Tip: Use T144 after T130 (Goods Upload) to verify unit configurations before issuing invoices. For agent invoicing, include the principal's tin to query goods authorized for that agent.

try {
    // Call T144: Goods Inquiry by Goods Code
    $response = $client->queryGoodsByCode(
        goodsCode: '0001,0002',           // Comma-separated goods codes
        tin: '1000029771'                 // Optional: principal TIN for agent queries
    );
    
    $items = $response['data']['content'] ?? $response;
    
    if (is_array($items) && count($items) > 0) {
        echo "✅ Retrieved " . count($items) . " goods configuration(s)\n";
        
        foreach ($items as $goods) {
            echo "   • Code: {$goods['goodsCode']}\n";
            echo "     Unit: {$goods['measureUnit']} (T115 rateUnit)\n";
            
            // Piece unit info
            if (($goods['havePieceUnit'] ?? '') === '101') {
                echo "     Piece Unit: {$goods['pieceMeasureUnit']} (scaled: {$goods['pieceScaledValue']})\n";
            }
            
            // Alternative units
            if (($goods['haveOtherUnit'] ?? '') === '101' && !empty($goods['goodsOtherUnits'])) {
                echo "     Alternative Units:\n";
                foreach ($goods['goodsOtherUnits'] as $alt) {
                    echo "       - {$alt['otherUnit']}: scaled {$alt['otherScaled']}, pkg {$alt['packageScaled']}\n";
                }
            }
        }
    } else {
        echo "⚠️  No enabled goods found for provided codes\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": "T144",
    "appId": "AP04",
    "version": "1.1.20191201",
    "tin": "1000029771",
    "deviceNo": "TCS9e0df01728335239",
    "taxpayerID": "1"
  }
}

Request Fields (Encrypted Payload)​

FieldRequiredTypeLengthDescription
goodsCode✅ YesStringUnlimitedOne or more goods codes separated by commas (e.g., "0001,0002"). Only goods with statusCode=101 (enabled) are returned.
tin❌ NoString≤20Principal agent TIN. Required when querying goods for agent invoicing workflows.

💡 Tip: Maximum practical limit for goodsCode list is ~50 codes per request. For larger batches, split into multiple calls.

Response Structure​

{
  "data": {
    "content": [
      {
        "goodsCode": "0001",
        "measureUnit": "101",
        "havePieceUnit": "101",
        "pieceMeasureUnit": "101",
        "haveOtherUnit": "101",
        "packageScaledValue": "1",
        "pieceScaledValue": "500",
        "goodsOtherUnits": [
          {
            "otherUnit": "AF",
            "otherScaled": "1000",
            "packageScaled": "1"
          }
        ]
      }
    ]
  },
  "globalInfo": {
    "interfaceCode": "T144",
    "returnStateInfo": {
      "returnCode": "00",
      "returnMessage": "SUCCESS"
    }
  }
}

Response Fields​

Goods Configuration Array Items​

FieldRequiredTypeDescription
goodsCode✅ YesString (≤50)Goods code (echoed from request)
measureUnit✅ YesString (3)Primary unit of measure code from T115 rateUnit dictionary
havePieceUnit✅ YesString (3)101=Yes (has piece unit), 102=No
pieceMeasureUnit❌ NoString (3)Piece unit code from T115 rateUnit; required if havePieceUnit=101, must be empty if 102
haveOtherUnit✅ YesString (3)101=Yes (has alternative units), 102=No
packageScaledValue✅ YesNumberScaling factor: 1 package = X measureUnit
pieceScaledValue✅ YesNumberScaling factor: 1 piece = X measureUnit
goodsOtherUnits❌ NoArrayAlternative unit mappings (only if haveOtherUnit=101)

goodsOtherUnits Array Items​

FieldRequiredTypeDescription
otherUnit✅ YesString (3)Alternative unit code from T115 rateUnit; cannot equal measureUnit or pieceMeasureUnit
otherScaled✅ YesNumberScaling factor: 1 otherUnit = X measureUnit
packageScaled✅ YesNumberScaling factor: 1 package = X otherUnit

💡 Tip: Use scaling values to convert quantities between units during invoice preparation. Example: if pieceScaledValue=500 and measureUnit=101 (per stick), then 1 piece = 500 sticks.

Return Codes​

CodeMessageDescription
00SUCCESSGoods configurations 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
2194goodsCode:cannot be empty!Missing goodsCode in request
2195goodsCode:Byte length cannot be greater than 50!Individual goods code exceeds limit
2255goodsCode:cannot be empty!Empty goods code in comma-separated list
2256goodsCode:Byte length cannot be greater than 50!Individual code in list exceeds limit
2835branchId:cannot be empty!Agent query requires valid branchId context
2836branchId:Byte length cannot be greater than 18!Branch ID format error
2837branchId does not belong to current taxpayer!Branch not owned by authenticated TIN
3104tin: If 'queryType' is 'Agent goods query', 'tin' cannot be emptyAgent query missing principal TIN
3106branchId does not belong to taxpayer '*'Branch ownership validation failed

💡 Tip: Goods not found or with statusCode≠101 are silently omitted from the response array—this is not an error condition.

Common Use Cases​

  1. Invoice Line Validation
    Verify unit of measure and scaling values before submitting T109 invoice lines to prevent 2243 (unit mismatch) errors.

  2. Agent Goods Authorization
    Query goods authorized for a specific agent by including the principal's tin to filter eligible items.

  3. Unit Conversion Logic
    Use packageScaledValue, pieceScaledValue, and goodsOtherUnits to build client-side quantity converters for multi-unit goods.

  4. Goods Configuration Cache Refresh
    Periodically call T144 for critical goods codes to detect URA-side unit configuration changes.

  5. Bulk Goods Setup Verification
    After uploading goods via T130, use T144 to confirm all codes were registered with expected unit configurations.

  6. Fuel Product Unit Validation
    For goodsTypeCode=102 (fuel), verify measureUnit matches EDC-compatible units from T171 before invoicing.

Integration Checklist​

✅ Validate each goodsCode is ≤50 characters before joining with commas
✅ Handle empty response array gracefully (goods not found or disabled)
✅ Cache response data with TTL to reduce API calls for frequently-used goods
✅ For agent workflows: validate tin belongs to an active principal before querying
✅ Cross-reference measureUnit, pieceMeasureUnit, and otherUnit values against T115 dictionary
✅ Use scaling values (packageScaledValue, pieceScaledValue, otherScaled) for accurate quantity conversions
✅ Log queried goods codes for audit trails in multi-tenant or agent environments
✅ Re-query goods configurations after T130 upload to confirm successful registration