Smart Registry

The normalization engine that transforms your internal SKUs into URA-compliant invoice lines automatically.

The Problem: Semantic Failures

90% of EFRIS integration failures aren't technical—they're semantic. Clients send simple data, but URA requires exact commodity codes, ISO units, and complex scaling math.

Common Rejection Reasons

• Unit Mismatch: Client sends "BAG", URA requires "KGM" or "TNE"
• Missing Commodity Code: "Chia Seeds" needs code "204024000000"
• Quantity Scaling: 10 Bags ≠ 10 Tonnes (Export requires conversion)
• Stock Unit Errors: Incorrect pieceQty causes inventory mismatch

The Solution: ProductMap

TaxBridge acts as a translation layer between your business language and URA's regulatory requirements. At its core is the ProductMap—a Rosetta Stone linking your SKUs to EFRIS metadata.

What You Send

externalRef: "CEMENT-50KG"

quantity: 10

unit: "BAG"

unitPrice: 50000

What TaxBridge Injects (Export)

goodsCode: "204024000000"

quantity: 0.5 (10 × 0.05)

unitOfMeasure: "TNE"

unitPrice: 1,000,000 (gross preserved)

pieceQty: 500 (10 × 50kg)

Understanding the Three Units

Every product can have up to three different unit representations. This is the most critical concept to understand for correct EFRIS compliance.

Field	Purpose	Who Uses It	Example
measureUnit	The Selling Unit (Invoice receipt)	The Buyer	"BAG" (Qty: 10)
pieceUnit	The Stock Unit (Inventory deduction)	URA EFRIS	"KGM" (Qty: 500)
exportUnit	The Customs Unit (International trade)	URA Customs	"TNE" (Qty: 0.5)

Common Mistake

Confusing pieceUnit with exportUnit will cause stock deduction errors. pieceUnit tells EFRIS how much inventory to deduct (500 KG), while exportUnit is for customs reporting (0.5 TNE).

ProductMap Object

Each mapping links your internal SKU to URA's commodity data and stores the conversion factors for automatic unit scaling.

{
  "id": "pm_abc123",
  "externalRef": "CEMENT-50KG",      // Your SKU
  
  // URA Master Data
  "goodsName": "Portland Cement",     
  "uraCode": "204024000000",          
  "categoryCode": "30111601",         // UNSPSC Category
  
  // Unit Configuration
  "measureUnit": "BAG",               // Selling Unit
  "pieceUnit": "KGM",                 // Stock Unit
  "exportUnit": "TNE",                // Customs Unit (optional)
  
  // Conversion Factors
  "pieceScalingFactor": 50,           // 1 BAG = 50 KGM
  "exportScalingFactor": 0.05         // 1 BAG = 0.05 TNE
}

API Usage

Creating a Product Mapping

curl -X POST https://api.taxbridge.app/v1/product-maps \
  -H "Authorization: Bearer sk_live_..." \
  -H "X-Tax-Payer-Id: tp_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "externalRef": "CEMENT-50KG",
    "goodsName": "Portland Cement 50KG Bag",
    "uraCode": "204024000000",
    "categoryCode": "30111601",
    "measureUnit": "BAG",
    "pieceUnit": "KGM",
    "pieceScalingFactor": 50,
    "exportUnit": "TNE",
    "exportScalingFactor": 0.05
  }'

Response

{ "id": "pm_abc123", "externalRef": "CEMENT-50KG", "status": "active" }

Using in a Tax Intent

Once mapped, just send your SKU. TaxBridge handles the rest.

curl -X POST https://api.taxbridge.app/v1/tax-intents \
  -H "Authorization: Bearer sk_live_..." \
  -H "X-Tax-Payer-Id: tp_abc123" \
  -d '{
    "taxMethodId": "EXPORT_ZERO_RATED",
    "externalRef": "INV-2025-001",
    "currency": "UGX",
    "items": [
      { "externalRef": "CEMENT-50KG", "quantity": 10, "unitPrice": 50000 }
    ]
  }'

Internally, the normalization engine will transform the item to 0.5 TNE @ 1,000,000 UGX and set pieceQty: 500.

The Golden Rule: Gross Preservation

When scaling quantities for export, the Gross Total must always be preserved. URA calculates tax on the gross. If we get this wrong, we create a tax liability mismatch.

Original Qty × Original Price = Scaled Qty × Scaled Price

Metric	Before (Client)	After (Normalized)	Math
Quantity	10 Bags	0.5 TNE	10 × 0.05
Unit Price	50,000	1,000,000	50,000 ÷ 0.05
Gross Total	500,000	500,000	✓ Preserved

Best Practices

Map Products Before Invoicing

Create all product mappings during onboarding, not during live invoice creation. This prevents runtime errors.

Get Scaling Factors Right

Double-check pieceScalingFactor (stock) and exportScalingFactor (customs). Errors here cause irrecoverable stock or tax discrepancies.

Use the Compliance Library

Search our synced URA Commodity Taxonomy to find the correct uraCode and categoryCode for your products.