Quickstart

Get your first invoice fiscalized in under 5 minutes. This guide covers authentication, product mapping, and your first successful submission to URA.

Prerequisites

API Keys

Get your sandbox API key from the TaxBridge Portal. Keys start with sk_test_ for sandbox or sk_live_ for production.

HTTP Client

Any language that can make HTTP requests (Node.js, Python, cURL, etc.).

1 Authentication

All API requests require two headers: your API key for authentication, and the taxpayer ID to identify which URA registration to use.

# Required headers for all requests

curl -H "Authorization: Bearer sk_test_your_api_key" \
     -H "X-Tax-Payer-Id: tp_abc123" \
     -H "Content-Type: application/json" \
     https://api.taxbridge.io/v1/tax-intents

Authorization

Your API key. Use sk_test_ for sandbox, sk_live_ for production.

X-Tax-Payer-Id

The taxpayer (business) making the sale. Get this from the Portal after onboarding.

2 Map Your Products

Before creating invoices, map your internal SKUs to URA's goods codes. This ensures automatic validation and tax compliance.

# POST /v1/product-maps

curl -X POST https://api.taxbridge.io/v1/product-maps \
  -H "Authorization: Bearer $TAXBRIDGE_API_KEY" \
  -H "X-Tax-Payer-Id: tp_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "externalRef": "CHIA-50KG",
    "uraCode": "204024000000",
    "goodsName": "Organic Chia Seeds",
    "measureUnit": "KGM",
    "categoryCode": "10101501",
    "refPrice": 50000
  }'

Response

{ "id": "pm_abc123", "externalRef": "CHIA-50KG", "goodsName": "Organic Chia Seeds", "measureUnit": "KGM", "uraCode": "204024000000" }

3 Create a Tax Intent

A Tax Intent is a draft invoice. TaxBridge validates it and prepares the URA payload automatically. Use your mapped SKUs in the items array.

# POST /v1/tax-intents

curl -X POST https://api.taxbridge.io/v1/tax-intents \
  -H "Authorization: Bearer $TAXBRIDGE_API_KEY" \
  -H "X-Tax-Payer-Id: tp_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "taxMethodId": "DOMESTIC_B2C",
    "externalRef": "INV-2025-001",
    "currency": "UGX",
    "paymentMode": "101",
    "buyerName": "John Doe",
    "items": [
      {
        "externalRef": "CHIA-50KG",
        "quantity": 10,
        "unitPrice": 50000,
        "unit": "KGM"
      }
    ]
  }'

Draft Created

{ "id": "ti_xyz789", "status": "READY_FOR_SUBMISSION", "totalGross": "500000.00", "externalRef": "INV-2025-001" }

Tax Method Options

DOMESTIC_B2C — Domestic sale to consumer
DOMESTIC_B2B — Domestic B2B (requires buyerTin)
EXPORT_ZERO_RATED — Zero-rated export (requires passport)

4 Confirm & Fiscalize

Once you're satisfied with the draft, confirm it to trigger fiscalization. TaxBridge handles encryption, signing, and submission to URA.

# POST /v1/tax-intents/:id/confirm

curl -X POST https://api.taxbridge.io/v1/tax-intents/ti_xyz789/confirm \
  -H "Authorization: Bearer $TAXBRIDGE_API_KEY"

Fiscalized!

{ "status": "SUCCEEDED", "fdn": "325042769062", "qrCode": "https://efris.ura.go.ug/validate?invoiceNo=325042769062" }

5 Check Status (Optional)

Fiscalization is asynchronous. Poll the GET endpoint to check the final status.

# GET /v1/tax-intents/:id

curl https://api.taxbridge.io/v1/tax-intents/ti_xyz789 \
  -H "Authorization: Bearer $TAXBRIDGE_API_KEY"

Status values: PROCESSING SUCCEEDED or FAILED

Quickstart

Prerequisites

API Keys

HTTP Client

1 Authentication

2 Map Your Products

3 Create a Tax Intent

Tax Method Options

4 Confirm & Fiscalize

5 Check Status (Optional)

Next Steps

Authentication Guide

Smart Registry

Webhooks

Error Handling