API Reference

Base URL: https://gateway.tarifix.xtellar.app/efrix/v1

Sandbox URL: https://gateway.tarifix.xtellar.app/efrix/v1/sandbox

---

Authentication

All requests require API key headers:

X-EFRIX-API-Key: efrix_live_abc123
X-EFRIX-API-Secret: sk_live_xyz789

Key Types:

• efrix_live_* - Production keys
• efrix_test_* - Sandbox keys

---

Invoices

Create Invoice

POST /invoices

Issue a new fiscal invoice to URA.

Request:

{
  "invoice_type": "NORMAL",
  "buyer": {
    "tin": "1000000001",
    "legal_name": "Acme Corporation Ltd",
    "business_name": "Acme Corp",
    "address": "Plot 1, Kampala Road, Kampala",
    "email": "accounts@acme.ug",
    "phone": "+256700000000"
  },
  "items": [
    {
      "name": "Widget A",
      "description": "Premium quality widget",
      "quantity": 10,
      "unit_price": 50000,
      "currency": "UGX",
      "tax_category": "STANDARD",
      "product_code": "WIDGET-001"
    }
  ],
  "payment_mode": "CREDIT",
  "payment_due_date": "2026-02-10"
}

Response (201 Created):

{
  "success": true,
  "data": {
    "id": "inv_abc123xyz",
    "fiscal_document_number": "FIS-2026-00001",
    "ura_verification_code": "EFRIS123456789",
    "qr_code_url": "https://api.tarifix.xtellar.app/efrix/qr/inv_abc123xyz.png",
    "qr_code_data": "https://efris.ura.go.ug/verify/EFRIS123456789",
    "status": "SUBMITTED",
    "totals": {
      "subtotal": 500000,
      "tax_amount": 90000,
      "total": 590000
    },
    "buyer": {
      "tin": "1000000001",
      "legal_name": "Acme Corporation Ltd"
    },
    "created_at": "2026-01-10T00:00:00Z"
  },
  "meta": {
    "request_id": "req_xyz789",
    "timestamp": "2026-01-10T00:00:00Z"
  }
}

---

List Invoices

GET /invoices

Query Parameters:

Response:

{
  "success": true,
  "data": [
    {
      "id": "inv_abc123xyz",
      "fiscal_document_number": "FIS-2026-00001",
      "status": "SUBMITTED",
      "total": 590000,
      "buyer_name": "Acme Corporation Ltd",
      "created_at": "2026-01-10T00:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "pages": 8
  }
}

---

Get Invoice

GET /invoices/{id}

Response: Full invoice object with all details.

---

Void Invoice

POST /invoices/{id}/void

Cancel a previously issued invoice.

Request:

{
  "reason": "Customer returned goods",
  "reason_code": "RETURN"
}

---

Issue Credit Note

POST /invoices/{id}/credit-note

Issue a credit note against an existing invoice.

Request:

{
  "items": [
    {
      "original_item_id": "item_123",
      "quantity": 2,
      "reason": "Defective products"
    }
  ]
}

---

Receipts

Create Receipt

POST /receipts

Issue a fiscal receipt (for immediate payment transactions).

Request:

{
  "buyer": {
    "name": "John Doe",
    "phone": "+256700000000"
  },
  "items": [
    {
      "name": "Coffee",
      "quantity": 1,
      "unit_price": 15000,
      "tax_category": "STANDARD"
    }
  ],
  "payment_mode": "CASH",
  "amount_paid": 15000
}

---

List Receipts

GET /receipts

Same query parameters as List Invoices.

---

Get Receipt

GET /receipts/{id}

---

Products

Register Product

POST /products

Register a new product with URA.

Request:

{
  "name": "Widget A",
  "description": "Premium quality widget",
  "unit_of_measure": "PCS",
  "unit_price": 50000,
  "currency": "UGX",
  "tax_category": "STANDARD",
  "product_code": "WIDGET-001",
  "barcode": "1234567890123"
}

---

List Products

GET /products

---

Update Product

PUT /products/{id}

---

Deactivate Product

DELETE /products/{id}

---

Stock

Increase Stock

POST /stock/increase

Record stock increase (purchases, production, adjustments).

Request:

{
  "product_id": "prod_123",
  "quantity": 100,
  "reason": "PURCHASE",
  "reference": "PO-2026-001",
  "supplier_tin": "1000000002"
}

---

Decrease Stock

POST /stock/decrease

Record stock decrease (sales, damage, adjustments).

Request:

{
  "product_id": "prod_123",
  "quantity": 10,
  "reason": "SALE",
  "reference": "INV-2026-001"
}

---

Transfer Stock

POST /stock/transfer

Transfer stock between locations.

---

Get Stock Levels

GET /stock

---

Taxpayer

Get Taxpayer Info

GET /taxpayer/info

Returns your registered business details from URA.

---

List Devices

GET /taxpayer/devices

---

Reports

Daily Summary

GET /reports/daily

Query: ?date=2026-01-10

---

Monthly Report

GET /reports/monthly

Query: ?year=2026&month=1

---

Tax Summary

GET /reports/tax-summary

Query: ?from=2026-01-01&to=2026-01-31

---

Export Report

POST /reports/export

Request:

{
  "type": "MONTHLY",
  "year": 2026,
  "month": 1,
  "format": "PDF"
}

Response:

{
  "success": true,
  "data": {
    "download_url": "https://api.tarifix.xtellar.app/efrix/exports/report_xyz.pdf",
    "expires_at": "2026-01-11T00:00:00Z"
  }
}

---

Error Responses

All errors follow this format:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid TIN format",
    "details": {
      "field": "buyer.tin",
      "expected": "10 digit number"
    }
  },
  "meta": {
    "request_id": "req_xyz789",
    "timestamp": "2026-01-10T00:00:00Z"
  }
}

Error Codes:

---

Rate Limits

Headers in responses:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1704844800

---

Webhooks

Configure webhooks in your dashboard to receive real-time events.

Event Types:

• invoice.created
• invoice.submitted
• invoice.failed
• invoice.voided
• receipt.created
• stock.updated

Payload:

{
  "event": "invoice.submitted",
  "timestamp": "2026-01-10T00:00:00Z",
  "data": {
    "id": "inv_abc123",
    "fiscal_document_number": "FIS-2026-00001"
  }
}

---

SDKs

• JavaScript/TypeScript
• Python
• PHP