https://github.com/axenda/zatca
An unofficial package to help developers implement ZATCA (Fatoora) QR code easily which is required for e-invoicing in Saudi Arabia.
https://github.com/axenda/zatca
e-invoicing fatoora javascript nodejs npm qr-code qrcode saudi-arabia typescript zatca
Last synced: about 2 months ago
JSON representation
An unofficial package to help developers implement ZATCA (Fatoora) QR code easily which is required for e-invoicing in Saudi Arabia.
- Host: GitHub
- URL: https://github.com/axenda/zatca
- Owner: axenda
- License: mit
- Created: 2021-11-18T18:52:56.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2023-07-19T05:36:23.000Z (over 2 years ago)
- Last Synced: 2025-10-18T16:50:17.516Z (4 months ago)
- Topics: e-invoicing, fatoora, javascript, nodejs, npm, qr-code, qrcode, saudi-arabia, typescript, zatca
- Language: TypeScript
- Homepage:
- Size: 769 KB
- Stars: 57
- Watchers: 2
- Forks: 13
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
# ZATCA (Fatoorah) QR-Code Implementation
[](https://npmjs.org/package/@axenda/zatca)
[](https://codecov.io/gh/axenda/zatca)
[](https://raw.githubusercontent.com/user/project/master/LICENSE)
An unofficial package to help developers implement ZATCA (Fatoora) QR code easily which is required for e-invoicing in
Saudi Arabia.
> ✨ You could use it in both frontend and backend Nodejs projects.
> ✅ Validated to have the same output as ZATCA's SDK as of 18 November 2021.
## Installation
To get started, install the package:
```bash
npm i --save @axenda/zatca
```
## Usage
### Summary
Simple, all you need to generate a QR code is:
```typescript
import { Invoice } from '@axenda/zatca';
const invoice = new Invoice({
sellerName: 'Axenda',
vatRegistrationNumber: '1234567891',
invoiceTimestamp: '2021-12-04T00:00:00Z',
invoiceTotal: '100.00',
invoiceVatTotal: '15.00',
});
const imageData = await invoice.render();
// Read the following sections for more details.
```
### Import
First, import Invoice class or Tag class to represent an invoice QR code:
```typescript
import { Invoice } from '@axenda/zatca';
// or
import { Tag } from '@axenda/zatca';
```
### Representing an invoice QR code
Second, create an instance of Invoice or an array of Tag class:
```typescript
const invoice = new Invoice({
sellerName: 'Axenda',
vatRegistrationNumber: '1234567891',
invoiceTimestamp: '2021-12-04T00:00:00Z',
invoiceTotal: '100.00',
invoiceVatTotal: '15.00',
});
// or
const tags: Tag[] = [
new Tag(1, 'Axenda'),
new Tag(2, '1234567891'),
new Tag(3, '2021-12-04T00:00:00Z'),
new Tag(4, '100.00'),
new Tag(5, '15.00'),
];
```
### Generate TLV
Now you can generate TLV string from the invoice or from the tags array:
```typescript
invoice.toTlv();
// or using tags array
import { toTlv } from '@axenda/zatca';
toTlv(tags)
```
### Generate Base64
You cloud generate Base64 string from the invoice or from the tags array:
```typescript
invoice.toBase64();
// or using tags array
import { tagsToBase64 } from '@axenda/zatca';
tagsToBase64(tags);
```
### Render QR code
You can generate image data (png) from base64 string and render it in browser:
```typescript
await invoice.render();
// or using tags array
import { renderTags } from '@axenda/zatca';
await renderTags(tags);
```
### Use QR code image data
Use the image data to display the QR code in browser:
```html
![]()
```
## Tests
To run test suites, first install dependencies, then run `npm test`:
```bash
npm install
npm test
```
## Package roadmap
- [x] Support ZATCA invoice QR code phase 1
- [ ] Review package API consistency
- [ ] Support ZATCA invoice QR code phase 2
## Contributing
We welcome [contributions](https://github.com/axenda/zatca/graphs/contributors) of all kinds from anyone. Please take a
moment to review the [guidelines for contributing](CONTRIBUTING.md).
* [Bug reports](https://github.com/axenda/zatca/issues/new)
* [Feature requests](CONTRIBUTING.md#-feature-requests)
* [Pull requests](CONTRIBUTING.md#-pull-requests)
## License
The MIT License (MIT). Please see [License File](LICENSE) for more information.