README

A Laravel 12 package for integrating with the Zambia Revenue Authority (ZRA) Smart Invoice system for POS applications.

Features

• Easy integration with Laravel 12 applications
• Seamless Inertia.js React/TypeScript components
• Device initialization with ZRA API
• Sales, purchase, and stock data submission
• Transaction logging and monitoring
• Configuration management
• Status indicators and analytics
• Support for various invoice types (NORMAL, COPY, TRAINING, PROFORMA) and transaction types
• Comprehensive tax handling with support for multiple tax categories
• Report generation (X and Z Reports)
• Inventory management with stock tracking and validation

What's New in 1.0.1

• Support for Various Invoice Types: Added configuration options for different invoice and transaction types
• Comprehensive Tax Handling: Support for multiple tax categories, zero-rated and exempt transactions
• Report Generation: X and Z reports for auditing and compliance purposes
• Inventory Management: Complete inventory tracking system with stock validation during sales

Installation

You can install the package via composer:

composer require mak8tech/zra-smart-invoice

Publishing Assets

Publish the package configuration and migrations:

php artisan vendor:publish --provider="Mak8Tech\ZraSmartInvoice\ZraServiceProvider"

Configuration

After publishing the package assets, you can configure the ZRA integration in the config/zra.php file.

You can also set these in your .env file:

ZRA_BASE_URL=https://api-sandbox.zra.org.zm/vsdc-api/v1
ZRA_TPIN=
ZRA_BRANCH_ID=
ZRA_DEVICE_SERIAL=
ZRA_DEBUG=false

Usage

Initialization

Initialize your device with ZRA:

use Mak8Tech\ZraSmartInvoice\Facades\Zra;

// Initialize device
$result = Zra::initializeDevice('1234567890', '001', 'DEVICE123456');

Sending Sales Data

use Mak8Tech\ZraSmartInvoice\Facades\Zra;

// Prepare sales data
$salesData = [
    'invoiceNumber' => 'INV-1234',
    'timestamp' => now()->format('Y-m-d H:i:s'),
    'invoiceType' => 'NORMAL', // Can also be COPY, TRAINING, PROFORMA
    'transactionType' => 'SALE', // Can also be CREDIT_NOTE, DEBIT_NOTE, ADJUSTMENT, REFUND
    'items' => [
        [
            'name' => 'Product 1',
            'quantity' => 2,
            'unitPrice' => 100.00,
            'totalAmount' => 200.00,
            'taxRate' => 16,
            'taxAmount' => 32.00,
            'taxCategory' => 'VAT', // Can also be TOURISM_LEVY, EXCISE_DUTY, etc.
        ],
    ],
    'totalAmount' => 200.00,
    'totalTax' => 32.00,
    'paymentType' => 'CASH',
    'customerTpin' => '',  // Optional for customer without TPIN
];

// Send to ZRA
$result = Zra::sendSalesData($salesData);

Generating Reports

use Mak8Tech\ZraSmartInvoice\Facades\Zra;

// Generate X report (interim report)
$xReport = Zra::generateXReport();

// Generate Z report (end of day report)
$zReport = Zra::generateZReport();

// Get daily summary report
$dailyReport = Zra::getDailyReport('2025-04-11');

Managing Inventory

use Mak8Tech\ZraSmartInvoice\Facades\Zra;

// Add new product to inventory
$product = Zra::addInventoryProduct([
    'code' => 'PROD001',
    'name' => 'Product Name',
    'description' => 'Product Description',
    'unitPrice' => 100.00,
    'taxRate' => 16,
    'taxCategory' => 'VAT',
    'initialStock' => 50
]);

// Update stock quantity
Zra::updateStockQuantity('PROD001', 60, 'STOCK_ADJUSTMENT', 'Inventory count adjustment');

// Check if product has sufficient stock
$hasStock = Zra::checkProductStock('PROD001', 5); // Returns true if at least 5 units available

Web Interface

The package includes a web interface accessible at /zra (configurable) where you can:

• Initialize your device
• View device status
• Test connectivity
• View transaction logs
• Generate X and Z reports
• Manage inventory and stock levels

Testing

composer test

Deployment to Packagist

For full instructions on deploying this package to Packagist.org, please see the Deployment Guide.

Changelog

Please see CHANGELOG for more information on what has changed recently.

License

The MIT License (MIT). Please see License File for more information.