ongudidan / vscu-php-sdk

v1.0.0 2026-10-12 10:17 UTC

Requires

• php: ^8.1
• guzzlehttp/guzzle: ^7.5

MIT

• Ongudidan

Published on Packagist.org on 2026-10-12 10:19 UTC

README

A comprehensive PHP SDK for integrating with the VSCU (Virtual Sales Control Unit) eTIMS API. This SDK provides a structured way to handle fiscal transactions, including Invoices and Credit Notes, using strongly typed DTOs and automatic tax calculations.

Installation

Install the package via Composer:

composer require ongudidan/vscu-php-sdk

Note: If you are using this as a local package in the Al-Amin ERP, ensure your root composer.json has the path repository configured.

Initialization

Initialize the Vscu client with your configuration:

use VscuSdk\Vscu;

$vscu = new Vscu([
    'base_url' => 'http://your-vscu-server:8088/', // VSCU Middleware Base URL
    'timeout'  => 30.0,
]);

Usage Guide

1. Creating a Sale (Invoice)

The SDK simplifies sale creation by handling item sequencing and tax calculations automatically.

use VscuSdk\DTOs\InvoiceDTO;

// 1. Create Invoice
$invoice = new InvoiceDTO();
$invoice->tin = 'P0XXXXXXXXM';
$invoice->bhfId = '00';
$invoice->trdInvcNo = 1001; 
$invoice->invcNo = 1001;
$invoice->salesDt = date('Ymd');
$invoice->cfmDt = date('YmdHis');
$invoice->stockRlsDt = date('YmdHis');
$invoice->regrNm = 'Admin';
$invoice->modrNm = 'Admin';

// 2. Set Customer (Optional, can be null)
$invoice->custTin = $request->input('custTin');
$invoice->custNm = $request->input('custNm');

// 3. Add Items (Taxes and line totals are calculated automatically from inclusive price)
$invoice->addItem([
    'itemCd'    => 'KE2OUU00000000000001',
    'itemClsCd' => '50131702',
    'itemNm'    => 'Fresh Milk 500ml',
    'price'     => 60.00, // Inclusive of tax
    'qty'       => 2,
    'taxType'   => 'B',    // 16% VAT
]);

$invoice->addItem([
    'itemCd'    => 'KE2OUU00000000000002',
    'itemClsCd' => '50161509',
    'itemNm'    => 'Sugar 1kg',
    'price'     => 150.00,
    'qty'       => 1,
    'taxType'   => 'B',
]);

// 3. Automatically calculate all totals and per-tax summaries
$invoice->calculateTotals();

// 4. Send to VSCU
try {
    $response = $vscu->sales()->saveSales($invoice->toArray());
    print_r($response);
} catch (\VscuSdk\Exceptions\VscuException $e) {
    echo "Error: " . $e->getMessage();
}

2. Creating a Credit Note (Refund)

The CreditNoteDTO behaves like InvoiceDTO but defaults to a refund receipt type.

Important

Sequential Numbers: Sales and Credit Notes must share the same sequential invcNo counter per BHF ID. Original Reference: orgInvcNo must be the full fiscal invoice number (e.g., KRACU0300010006/5). Mandatory Fields: rfdRsnCd and rfdDt are required for credit notes.

use VscuSdk\DTOs\CreditNoteDTO;

$creditNote = new CreditNoteDTO();
$creditNote->tin = 'P0XXXXXXXXP';
$creditNote->bhfId = '00';
$creditNote->orgInvcNo = 'KRACU0300010006/5'; // Reference to original fiscal invoice
$creditNote->trdInvcNo = 'CN-2024-0001'; // Internal system number
$creditNote->invcNo = 1005; // SHARED sequence with Sales

$creditNote->salesDt = date('Ymd');
$creditNote->cfmDt = date('YmdHis');
$creditNote->stockRlsDt = date('YmdHis');

// Mandatory Refund Fields
$creditNote->rfdDt = date('Ymd');
$creditNote->rfdRsnCd = '01'; // 01: Sales Return, 02: Post-sale discount, etc.

$creditNote->regrId = '1';
$creditNote->regrNm = 'Admin';
$creditNote->modrId = '1';
$creditNote->modrNm = 'Admin';

// Add the items being returned
$creditNote->addItem([
    'itemCd'    => 'KE2OUU00000000000001',
    'itemClsCd' => '50131702',
    'itemNm'    => 'Fresh Milk 500ml',
    'price'     => 60.00,
    'qty'       => 1,
    'taxType'   => 'B',
]);

$creditNote->calculateTotals();

try {
    $response = $vscu->sales()->saveSales($creditNote->toArray());
    print_r($response);
} catch (\VscuSdk\Exceptions\VscuException $e) {
    echo "Error: " . $e->getMessage();
}

Available Resources

Sales Resource ($vscu->sales())

• saveSales(array $data): Submit an invoice.
• saveCreditNote(array $data): Submit a credit note.
• selectItems(array $query): Search for items in VSCU.

Items Resource ($vscu->items())

• saveItem(array $data): Register or update an item in eTIMS.
• getItemList(array $query): Retrieve registered items.
• getItemClsList(array $query): Retrieve KRA item classifications.

Customers Resource ($vscu->customers())

• selectCustomer(array $query): Lookup customer details by TIN.

Error Handling

All API errors throw a VscuSdk\Exceptions\VscuException.

try {
    // API Call
} catch (\VscuSdk\Exceptions\VscuException $e) {
    // Handle error
}

Tax Types

The SDK uses the taxType parameter to determine how to calculate taxes. The following types are supported based on KRA eTIMS standards:

Type	Description	Rate	Usage
A	Exempt	0%	Items specifically exempt from VAT
B	Standard Rate	16%	Most taxable goods and services
C	Zero Rated	0%	Exports, certain basic food items, etc.
D	Non-VAT	0%	Items outside the scope of VAT
E	8% Rate	8%	Petroleum products (Fuel)

DTO Fields Guide

Refer to the VSCU Docs folder for detailed field definitions.

• pmtTyCd: 01 (Cash), 02 (Credit), 03 (Mobile Money), etc.