VirtualDeviceLib Documentation

Virtual Device Documentation v1.0.0

Overview

VirtualDeviceLib is a C# library (DLL) used to interact with a Fiscal Device Management System (FDMS). This library provides several public methods to fetch device configurations, check device status, manage fiscal days, and process Fiscal Documents. This documentation offers basic examples of how to load the library in a C# application, call its methods, and handle possible error scenarios.

Referencing

To include VirtualDeviceLib in your project, reference the DLL in your Visual Studio project.

1. Right-click on the References section in your project.
2. Click on Add Reference.
3. Browse to the location (preferably your application path) of the VirtualDeviceLib DLL and add it.

Usage Example

1. Loading and Using the Library

using VirtualDeviceLib;
using Newtonsoft.Json.Linq;

namespace TestVirtualDeviceApp
{
    class Program
    {
        static void Main(string[] args)
        {
            // Create an instance of the library
            var virtualDevice = new VirtualDevice();

            // Example: Fetch Device Configurations
            string configResult = virtualDevice.GetConfig();
            Console.WriteLine($"Device Config Result: {configResult}");

            // Example: Check Device Status
            string statusResult = virtualDevice.GetStatus();
            Console.WriteLine($"Device Status Result: {statusResult}");
        }
    }
}

2. Standard Responses

Error Response:

{
    "Code": "0",
    "Message": "Error Message"
}

Success Response:

{
    "Code": "1",
    "Message": "Success Message",
    "QRCode": "",
    "FDMSInvoiceNo": "",
    "FiscalDayNo": "",
    "VerificationCode": "",
    "VerificationLink": "https://fdmstest.zimra.co.zw",
    "DeviceID": "18489",
    "Data": {...}
}

Public Methods

GetConfig()

• Fetches the device configurations from the FDMS server.
• Returns: Success message with configuration details or an error message.

Example:

string config = virtualDevice.GetConfig();

GetStatus()

• Retrieves the current status of the device from the FDMS server.
• Returns: Success message with status details or an error message.

Example:

string status = virtualDevice.GetStatus();

OpenFiscalDay()

• Opens a new fiscal day on the FDMS server, provided the last fiscal day is closed.
• Returns: Success message with the Z Report data for the previous fiscal day or an error message.

Example:

string openFiscalDayResult = virtualDevice.OpenFiscalDay();

CloseFiscalDay()

• Closes the current fiscal day on the FDMS server.
• Returns: Success message with the Z Report data for the current fiscal day or an error message.

Example:

string closeFiscalDayResult = virtualDevice.CloseFiscalDay();

SubmitReceipt(...)

• Submits a Fiscal Invoice, Credit Note, or Debit Note to the FDMS server.
• Returns: Success message with the QR Code and Receipt Information as the Data value or an error message.

Example:

var myReceiptLines = new List<receiptLine>
{
    new receiptLine()
    {
        receiptLineName = "Test Item 1",
        receiptLinePrice = 100.00M,
        receiptLineQuantity = 1,
        receiptLineTotal = 100.00M,
        taxCode = "B",
        taxPercent = 0M
    }
};
string receiptLines = JsonConvert.SerializeObject(myReceiptLines);

var submitReceipt = virtualDevice.SubmitReceipt("FiscalInvoice", "USD", "INV001", "REF000", 110.00M, 13.04M, "Test Invoice", receiptLines, true, "CASH", "InvoiceA4", "Axis Solutions Pvt Ltd", "Axis Solutions", "123456789", "1234567890", "0770000000", "developers@axissol.com", "Harare", "Bargate Road, Vainona", "60", "Harare");

GetLicense()

• Gets the device license status.
• Returns: Success message with the license details or an error message.

Example:

string getLicenseResult = virtualDevice.GetLicense();

Error Guide

GetConfig() Errors

• Error: “Failed to get Device Configurations”
• Fix:
  • Ensure the device is connected to the FDMS server.
  • Check network connectivity between the device and server.
  • Verify that the correct device ID is being used.

GetStatus() Errors

• Error: “Failed to get Device Status”
• Fix:
  • Ensure the device is properly connected to the network.
  • Check if the FDMS server is reachable.
  • Verify if the device configuration is correct.

OpenFiscalDay() Errors

• Error: “Failed to open a new Fiscal Day”

• Fix:

  • Ensure the previous fiscal day is closed before attempting to open a new one.
  • Check the status of the device to verify if the day is open or closed.

• Error: “Fiscal Day No: {number} is already open”

• Fix:

  • Close the currently open fiscal day before opening a new one.

SubmitReceipt() Errors

• Error: “Device License Error - Device Not Licensed”

• Fix:

  • Ensure that the device has a valid license installed.
  • Verify the license payment status with the license provider.

• Error: “Invoice Number already exists in your fiscal records”

• Fix:

  • Use a unique invoice number for each transaction.
  • Review existing fiscal records for the invoice number in question.

GetLicense() Errors

• Error: “License Status: Device Not Licensed”
• Fix:
  • Ensure the device license is paid and activated.
  • Open fiscal day to load license if it has been recently paid or activated.