VSDC SDK

A plug-and-play TypeScript/Node.js SDK for the Zambia Revenue Authority (ZRA) Smart Invoice VSDC integration.

Features

• Typed Interfaces: Full TypeScript support for all requests and responses.
• Validation: Runtime validation using Zod ensures you send correct data.
• Constants: Pre-defined enums for Tax Types, Product Types, Units, etc.
• Helpers: Automatic tax total calculation for sales.

Installation

npm install vsdc-zra-sdk

Usage

1. Configuration

Initialize the client with your VSDC settings.

import { VSDCClient } from "vsdc-zra-sdk";

const client = new VSDCClient({
  baseUrl: "http://localhost:8080", // URL of your local VSDC
  tpin: "1000000000",
  bhfId: "000",
  deviceSerialNo: "DVC12345678", // Optional, needed for initialization
});

2. Device Initialization

Run this once when setting up the VSDC.

try {
  const result = await client.initializeDevice();
  console.log("Device Initialized:", result);
} catch (error) {
  console.error("Initialization failed:", error);
}

3. Register an Item

import { ProductType, PackagingUnit, QuantityUnit, TaxType } from "vsdc-zra-sdk";

const newItem = {
  itemCd: "ITM001",
  itemClsCd: "5059690800", // ZRA Item Class Code
  itemTyCd: ProductType.FinishedProduct,
  itemNm: "Sample Widget",
  pkgUnitCd: PackagingUnit.Net,
  qtyUnitCd: QuantityUnit.Piece,
  taxTyCd: TaxType.StandardRated,
  dftPrc: 100.00,
  regrNm: "Admin",
  regrId: "admin",
  modrNm: "Admin",
  modrId: "admin",
};

const response = await client.saveItem(newItem);
console.log("Item Saved:", response);

4. Submit a Sale (Invoice)

The SDK automatically calculates tax totals if you use the simplified interface.

import { TransactionType, ReceiptType, PaymentMethod, TaxType } from "vsdc-zra-sdk";

const sale = {
  invcNo: 1001,
  salesTyCd: TransactionType.Normal,
  rcptTyCd: ReceiptType.Sale,
  pmtTyCd: PaymentMethod.Cash,
  salesSttsCd: "02", // Approved
  cfmDt: "20231222100000",
  salesDt: "20231222",
  regrNm: "Cashier",
  regrId: "CSH01",
  modrNm: "Cashier",
  modrId: "CSH01",
  // List of items in the cart
  items: [
    {
      itemSeq: 1,
      itemCd: "ITM001",
      itemClsCd: "5059690800",
      itemNm: "Sample Widget",
      pkgUnitCd: "NT",
      pkg: 1,
      qtyUnitCd: "U",
      qty: 2,
      prc: 100.00,
      splyAmt: 200.00,
      taxTyCd: TaxType.StandardRated, // 'A' (16%)
      taxblAmt: 200.00,
      taxAmt: 32.00,
      totAmt: 232.00,
    }
  ],
};

// The SDK will calculate totTaxblAmt, totTaxAmt, totAmt, and breakdown by tax type
const invoiceResponse = await client.saveSales(sale);
console.log("Invoice Submitted:", invoiceResponse);

5. Managing Stock

import { StockIOSaveReq } from "vsdc-zra-sdk";

// Adjust stock (In/Out)
const stockAdjustment = {
  sarNo: 2023001,
  regTyCd: "M",
  sarTyCd: "11", // Stock In
  ocrnDt: "20231201",
  totItemCnt: 1,
  totTaxblAmt: 1000,
  totTaxAmt: 160,
  totAmt: 1160,
  regrNm: "Admin",
  regrId: "admin",
  modrNm: "Admin",
  modrId: "admin",
  itemList: [
    {
      itemSeq: 1,
      itemCd: "ITM001",
      itemClsCd: "5059690800",
      itemNm: "Widget",
      pkgUnitCd: "NT",
      pkg: 10,
      qtyUnitCd: "U",
      qty: 10,
      prc: 100,
      splyAmt: 1000,
      taxblAmt: 1000,
      taxTyCd: "A",
      taxAmt: 160,
      totAmt: 1160
    }
  ]
};

await client.saveStockIO(stockAdjustment);

6. Purchases

const purchase = {
    invcNo: 500,
    pchsDt: "20231201",
    totItemCnt: 1,
    totTaxblAmt: 500,
    totTaxAmt: 80,
    totAmt: 580,
    // ... other required fields mapping to TrnsPurchaseSaveReq
    itemList: []
};
await client.savePurchase(purchase);

7. Other Modules

The SDK supports all 8 VSDC modules:

• Notices: getNotices()
• Branches: getBranches(), saveBranchCustomer(), saveBranchUser()
• Imports: getImportItems(), updateImportItem()
• Code Data: getCodes(), getItemClassifications()

Constants

The SDK exports enums for common VSDC codes:

• TaxType: StandardRated (A), Exempt (D), etc.
• ProductType: RawMaterial, FinishedProduct, Service.
• PackagingUnit: Net, Box, Bottle, etc.
• QuantityUnit: Piece, Kg, Litre.
• PaymentMethod: Cash, Card, MobileMoney.

License

MIT