Virtual Webservice Documentation

Overview

Virtual Webservice is 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 you can consume the endpoints and handle possible error scenarios.

1. Hosting

This webservice can be hosted on a Windows Machine on IIS.

Webservice Installation and Configuration
Swagger URL for Development: http://140.82.25.196:10005/

Note: We are available to assist with the installation of the web service. Should you encounter any issues, we can also host the web service on your behalf. Please note that the base URL may vary depending on the web service configuration. In this development instance, the base URL is: http://140.82.25.196:10005

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": {...}
}

3. Webservice Endpoints to Consume

`GetConfig` (GET)

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

Example:

http://140.82.25.196:10005/api/VirtualDevice/GetConfig

`GetStatus` (GET)

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

Example:

http://140.82.25.196:10005/api/VirtualDevice/GetStatus

`OpenFiscalDay` (GET)

Description: 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:

http://140.82.25.196:10005/api/VirtualDevice/OpenFiscalDay

`CloseFiscalDay` (GET)

Description: 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:

http://140.82.25.196:10005/api/VirtualDevice/CloseFiscalDay

`SubmitReceipt` (POST)

Example:

http://140.82.25.196:10005/api/VirtualDevice/SubmitReceipt

Description: Submit 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.

Sample Payload:

{
 "ReceiptType": "FiscalInvoice",
 "ReceiptCurrency": "ZWG",
 "InvoiceNo": "1",
 "ReferenceNumber": "",
 "InvoiceAmount": 1.00,
 "InvoiceTaxAmount": 0,
 "ReceiptNotes": "Invoice",
 "ReceiptLinesTaxInclusive": true,
 "MoneyTypeCode": "Cash",
 "ReceiptPrintForm": "Receipt48",
 "BuyerRegisterName": "",
 "BuyerTradeName": "",
 "VatNumber": "",
 "BuyerTIN": "",
 "BuyerPhoneNo": "",
 "BuyerEmail": "",
 "BuyerProvince": "",
 "BuyerStreet": "",
 "BuyerHouseNo": "",
 "BuyerCity": "",
 "ReceiptLines": [
 {
 "ReceiptLineType": "Sale",
 "ReceiptLineNo": 1,
 "ReceiptLineHSCode": "",
 "ReceiptLineName": "Bread",
 "ReceiptLinePrice": 1.00,
 "ReceiptLineQuantity": 1,
 "ReceiptLineTotal": 1.00,
 "TaxCode": "A",
 "TaxPercent": 0
 }
 ]
}

Note: Customer details (Buyer Information) are mandatory if the purchasing company is VAT registered.

4. 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.

`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.

Virtual Fiscalisation