SDK Documentation

Official SDK libraries for integrating with the EFRIX API.

---

JavaScript / TypeScript {#javascript}

Installation

npm install @xtellar/efrix
# or
yarn add @xtellar/efrix
# or
bun add @xtellar/efrix

Quick Start

import { EfrixClient } from '@xtellar/efrix';

const efrix = new EfrixClient({
  apiKey: process.env.EFRIX_API_KEY!,
  apiSecret: process.env.EFRIX_API_SECRET!,
  sandbox: false // Set to true for testing
});

// Create an invoice
const invoice = await efrix.invoices.create({
  buyer: {
    tin: '1000000001',
    legalName: 'Acme Corporation Ltd',
    email: 'accounts@acme.ug'
  },
  items: [
    {
      name: 'Widget A',
      quantity: 10,
      unitPrice: 50000,
      taxCategory: 'STANDARD'
    }
  ],
  paymentMode: 'CREDIT',
  paymentDueDate: '2026-02-10'
});

console.log(invoice.fiscalDocumentNumber);
console.log(invoice.qrCodeUrl);

API Reference

EfrixClient

new EfrixClient(options: EfrixOptions)

Invoices

// Create invoice
efrix.invoices.create(data: CreateInvoiceRequest): Promise<Invoice>

// List invoices
efrix.invoices.list(options?: ListOptions): Promise<PaginatedResponse<Invoice>>

// Get invoice by ID
efrix.invoices.get(id: string): Promise<Invoice>

// Void invoice
efrix.invoices.void(id: string, reason: VoidReason): Promise<Invoice>

// Issue credit note
efrix.invoices.createCreditNote(id: string, data: CreditNoteRequest): Promise<Invoice>

Receipts

efrix.receipts.create(data: CreateReceiptRequest): Promise<Receipt>
efrix.receipts.list(options?: ListOptions): Promise<PaginatedResponse<Receipt>>
efrix.receipts.get(id: string): Promise<Receipt>

Products

efrix.products.create(data: CreateProductRequest): Promise<Product>
efrix.products.list(options?: ListOptions): Promise<PaginatedResponse<Product>>
efrix.products.update(id: string, data: UpdateProductRequest): Promise<Product>
efrix.products.delete(id: string): Promise<void>

Stock

efrix.stock.increase(data: StockAdjustment): Promise<StockResponse>
efrix.stock.decrease(data: StockAdjustment): Promise<StockResponse>
efrix.stock.getAll(productId?: string): Promise<StockLevel[]>

Error Handling

import { EfrixError, ValidationError, AuthenticationError } from '@xtellar/efrix';

try {
  const invoice = await efrix.invoices.create(data);
} catch (error) {
  if (error instanceof ValidationError) {
    console.error('Validation failed:', error.details);
  } else if (error instanceof AuthenticationError) {
    console.error('Invalid credentials');
  } else if (error instanceof EfrixError) {
    console.error('EFRIX error:', error.code, error.message);
  }
}

TypeScript Types

import type {
  Invoice,
  Receipt,
  Product,
  Buyer,
  InvoiceItem,
  CreateInvoiceRequest,
  CreateReceiptRequest
} from '@xtellar/efrix';

---

Python {#python}

Installation

pip install efrix

Quick Start

from efrix import EfrixClient

client = EfrixClient(
    api_key="efrix_live_abc123",
    api_secret="sk_live_xyz789",
    sandbox=False
)

# Create an invoice
invoice = client.invoices.create(
    buyer={
        "tin": "1000000001",
        "legal_name": "Acme Corporation Ltd"
    },
    items=[
        {
            "name": "Widget A",
            "quantity": 10,
            "unit_price": 50000,
            "tax_category": "STANDARD"
        }
    ],
    payment_mode="CREDIT"
)

print(invoice.fiscal_document_number)
print(invoice.qr_code_url)

API Reference

Client Initialization

from efrix import EfrixClient

client = EfrixClient(
    api_key: str,          # Required
    api_secret: str,       # Required
    sandbox: bool = False, # Optional
    timeout: int = 30      # Optional, in seconds
)

Invoices

# Create
invoice = client.invoices.create(**data)

# List
invoices = client.invoices.list(page=1, limit=20, status="SUBMITTED")

# Get
invoice = client.invoices.get(id="inv_abc123")

# Void
invoice = client.invoices.void(id="inv_abc123", reason="RETURN", description="...")

# Credit Note
credit = client.invoices.create_credit_note(id="inv_abc123", items=[...])

Products

product = client.products.create(name="Widget", unit_price=50000, tax_category="STANDARD")
products = client.products.list()
product = client.products.update(id="prod_123", name="Updated Widget")
client.products.delete(id="prod_123")

Error Handling

from efrix.exceptions import EfrixError, ValidationError, AuthenticationError

try:
    invoice = client.invoices.create(**data)
except ValidationError as e:
    print(f"Validation failed: {e.details}")
except AuthenticationError:
    print("Invalid credentials")
except EfrixError as e:
    print(f"Error {e.code}: {e.message}")

---

PHP {#php}

Installation

composer require xtellar/efrix-php

Quick Start

<?php
require 'vendor/autoload.php';

use Xtellar\Efrix\EfrixClient;

$efrix = new EfrixClient([
    'api_key' => getenv('EFRIX_API_KEY'),
    'api_secret' => getenv('EFRIX_API_SECRET'),
    'sandbox' => false
]);

// Create an invoice
$invoice = $efrix->invoices->create([
    'buyer' => [
        'tin' => '1000000001',
        'legal_name' => 'Acme Corporation Ltd'
    ],
    'items' => [
        [
            'name' => 'Widget A',
            'quantity' => 10,
            'unit_price' => 50000,
            'tax_category' => 'STANDARD'
        ]
    ],
    'payment_mode' => 'CREDIT'
]);

echo $invoice->fiscal_document_number;
echo $invoice->qr_code_url;

Error Handling

use Xtellar\Efrix\Exceptions\EfrixException;
use Xtellar\Efrix\Exceptions\ValidationException;

try {
    $invoice = $efrix->invoices->create($data);
} catch (ValidationException $e) {
    echo "Validation error: " . $e->getMessage();
    print_r($e->getDetails());
} catch (EfrixException $e) {
    echo "Error: " . $e->getCode() . " - " . $e->getMessage();
}

---

SDK Status

Note: SDKs are planned for future releases. In the meantime, use the REST API directly with HTTP libraries.