https://github.com/takumade/zimra-fdms-js
Javscript library for using ZIMRA's FDMS API
https://github.com/takumade/zimra-fdms-js
fdms javascript tax typescript zimbabwe zimra
Last synced: 10 months ago
JSON representation
Javscript library for using ZIMRA's FDMS API
- Host: GitHub
- URL: https://github.com/takumade/zimra-fdms-js
- Owner: takumade
- Created: 2025-02-02T17:01:23.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-02-02T17:20:16.000Z (over 1 year ago)
- Last Synced: 2025-02-02T18:23:08.178Z (over 1 year ago)
- Topics: fdms, javascript, tax, typescript, zimbabwe, zimra
- Homepage:
- Size: 2.93 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Fiscal Device Management System (FDMS) JS API Client
"Pay you taxes 🤑💸"
This repository provides a Node.js client for interacting with the Fiscal Device Gateway API (aka FDMS) provided by ZIMRA. This library is a port of [Lord Sky's Python FDMS API](https://github.com/lordskyzw/zimra-public) and is intended to provide similar functionality. The client can be used to manage various operations related to fiscal devices, such as registering a device, fetching configurations, issuing certificates, and handling fiscal day operations.
PLEASE NOTE THAT THE FDMS IS A STATEFUL SYSTEM, SO YOU NEED TO KEEP TRACK OF THE FISCAL DAY NUMBER AND THE RECEIPT COUNTERS. THE CLIENT DOES NOT KEEP TRACK OF THESE FOR YOU
## Table of Contents
- [Stack](#stack)
- [Installation](#installation)
- [Usage](#usage)
- [Todo](#todo)
- [Class Methods](#class-methods)
- [Contributing](#contributing)
- [License](#license)
- [Special Thanks](#special-thanks)
## Stack
- [TypeScript](https://www.typescriptlang.org/) - Programming Language
- [Axios](https://axios-http.com/) - Network requests
- [Node-Forge](https://github.com/digitalbazaar/node-forge) - Cryptography library
- [Asana](https://asana.com/) - Project Management
## Installation
To use this client, clone the repository and install the necessary dependencies:
```bash
git clone https://github.com/takumade/zimra-fdms-js.git
cd zimra-fdms-js
npm install
```
Or you can use other package managers:
```bash
npm install zimra-fdms
```
```bash
pnpm install zimra-fdms
```
```bash
yarn add zimra-fdms
```
## Usage
You can use the `FiscalDevice` class to interact with the Fiscal Device Gateway API. Below is an example of how to initialize the class and perform some operations.
### Example
```typescript
const { FiscalDevice } = require(' zimra-fdms');
// Initialize the device in test mode
const device = FiscalDevice(
device_id: str,
serialNo: str,
activationKey: str,
cert_path: str,
private_key_path:str,
test_mode:bool =True,
deviceModelName: str='Model123',
deviceModelVersion:str = '1.0',
company_name:str ="Nexus"
)
// Open a fiscal day
fiscalDayStatus = device.openDay(fiscalDayNo=102)
console.log(fiscalDayStatus)
```
```typescript
// Submit a receipt
let exampleInvoice = {
"deviceID": 12345,
"receiptType": "FISCALINVOICE",
"receiptCurrency": "USD",
"receiptCounter": 1,
"receiptGlobalNo": 1,
"invoiceNo": "mz-1",
"receiptDate": datetime.now().strftime('%Y-%m-%dT%H:%M:%S'), #example: "2021-09-30T12:00:00",
"receiptLines": [
{"item_name": "0percent_item",
"tax_percent": 0.00,
"quantity": 1,
"unit_price": 10.00
},
{"item_name": "15percent_item2",
"tax_percent": 15.00,
"quantity": 1,
"unit_price": 20.00
}
],
"receiptPayments":[{
"moneyTypeCode": 0,
"paymentAmount": 30.00
}]
}
let receipt = device.prepareReceipt(example_invoice) // this method does all the heavy lifting for you
let receiptStatus = device.submitReceipt(receipt) // this method submits the receipt to the fiscal device management system and if the receipt has no errors, a QR url is returned which can be used to make the qr code to be printed on receipt, otherwise it returns the error message
console.log(receiptStatus)
```
## Todo
- [x] Port `FiscalDevice` class Part 1 of 7
- [x] Port `FiscalDevice` class Part 2 of 7
- [x] Port `FiscalDevice` class Part 3 of 7
- [x] Port `FiscalDevice` class Part 4 of 7
- [x] Port `FiscalDevice` class Part 5 of 7
- [x] Port `FiscalDevice` class Part 6 of 7
- [x] Port `FiscalDevice` class Part 7 of 7
- [x] Add general FMDS tests
- [x] Add tests for `FiscalDevice` class
- [] Test library
- [ ] Deploy to npm
## Class Methods
### `constructor(test_mode=False, *args)`
Initializes the Device class.
- `test_mode`: Boolean to specify whether to use the test environment or production environment.
### `register()`
Registers the device.
### `getConfig()`
Fetches the device configuration and updates the device attributes.
### `issueCertificate()`
Issues a certificate for the device.
### `getStatus()`
Gets the current status of the device.
### `openDay(fiscalDayNo, fiscalDayOpened=None)`
Opens a fiscal day.
### `prepareReceipt(receiptData)`
Prepares a receipt to be submitted to the fiscal device management system.
It calculates the taxes and formats them in the required format
It signs the receipt as well using the private key provided
### `submitReceipt(receiptData)`
Submits a receipt to the fiscal device gateway.
### `closeDay()`
Closes the fiscal day.
It also creates the fiscal day signature based on all the day's transactions
## Contributing
Contributions are welcome! Please open an issue or submit a pull request for any changes.
This project is still in development and there are many features that can be added to make work simpler for front end developers
## License
This project is licensed under the MIT License. See the LICENSE file for details.
## Special Thanks
- [Zimra](https://zimra.co.zw) for providing the FDMS system and the API documentation.
- [Lord Sky](https://github.com/lordskyzw) for the open source work on the [Python FDMS API](https://github.com/lordskyzw/zimra-public)