🔐 FIRS e-Invoicing

A comprehensive Node.js package with CLI support for securely encrypting IRNs (Invoice Reference Numbers) and certificates, generating QR codes, and decrypting invoice data — specifically built for digital tax systems like Nigeria's FIRS e-Invoicing platform.

---

🚀 Features

• 🔒 Secure Encryption: RSA encryption for IRNs and certificates using public keys
• 🔓 Reliable Decryption: Decrypt encrypted invoice payloads with private keys
• 📱 QR Code Generation: Generate QR codes as PNG images and base64 strings
• 📦 Flexible Integration: Use as Node.js module or standalone CLI tool
• ⚡ High Performance: Optimized for production environments
• 🧪 Well Tested: Extensive test coverage for reliability

---

📦 Installation

Using npm

1# For local/embedded use
2npm install firs-einvoicing
3
4# Global installation for CLI access
5npm install -g firs-einvoicing

Using Yarn

1# For local/embedded use
2yarn add firs-einvoicing
3
4# Global installation for CLI access
5yarn global add firs-einvoicing

Using pnpm

1# For local/embedded use
2pnpm add firs-einvoicing
3
4# Global installation for CLI access
5pnpm add -g firs-einvoicing

Quick CLI Usage (No Installation Required)

1npx firs-einvoicing encrypt --irn "IRN123-0FD6C95D-20250609" --certificate "..." --publicKey "..."

---

📖 Usage

✨ As a Node.js Library

ES Modules (ESM)

1import { decryptInvoice, generateQRCode } from "firs-einvoicing";
2import fs from "fs";
3
4try {
5  // Encrypt IRN and generate QR code
6  const encryptionResult = await generateQRCode({
7  // NOTE: You do not need to provide a timestamp manually. A timestamp is automatically generated at the time of processing.
8    irn: "IRN123-0FD6C95D-20250609",
9    certificate: "bEF0V3FJbmo5cVZYbEdCblB4QVpjMG9HVWFrc29GM2hiYWFkYWMyODRBUT0=",
10    publicKey:
11      "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUlJQklqQU5CZ2txaGtpRzl3MEJBUUVGQUFPQ0FROEFNSUlCQ2dLQ0FRRUFyU0xpdDRtb1RMbFdjd1A4eEp6RQp3ZTdkRHExdC9kMi9zcXdQTlNVandablFPbklabVh4TXY4QUQxemMxdUErZ3VCc2tpUGdo",
12    size: 300,
13    fgColor: "#000000",
14    bgColor: "#00FFFF",
15      logo: "https://example.com/logo.png",
16    logoSizeRatio: 0.2,
17  });
18
19    console.log("QR Code Buffer:", encryptionResult.qrCodeBuffer);
20    console.log("Base64 QR Code:", encryptionResult.qrCodeDataUrl);
21    console.log("Encrypted Base64:", encryptionResult.encryptedBase64);
22
23
24
25
26    
27  // Decrypt encrypted payload
28  const decryptedData = await decryptInvoice({
29    iv_hex: "4342576a6a65397a38394e6e73423478",
30    pub: "Zd22h6lAZeX667t9YKQ5Teua",
31    ciphertext:
32      "TlrxIxmimiXXJafQztd-y5L3_vIrmHBG5YnE9vR6usrAzQm5gx3TmwKzNYr8RVIKuRBTQuEkRSReS5YbBMP_B7DXuPssTajBkpycz_Gugb7_Ro4XZLCjSRD5ckT3diPCBbbAtk8C-QNtFAR4xRT-tF9fV5e3DfmQMbO6kiARU21eeXvf4YLDwS3RlQHaGrIi2d1TqqvIxWDk8VXeFpDUw56cyH_I3340zut2-FPZ",
33    api_key: "da5811ef-9c4e-42f1-ab4c-af654470c0ca",
34  });
35
36  console.log("Decrypted Invoice:", decryptedData);
37} catch (error) {
38  console.error("Encryption/Decryption failed:", error.message);
39}

---

🔧 API Reference

generateQRCode(options)

Parameters:

Encrypts IRN and certificate data, then generates a QR code.

Name	Type	Required	Description
irn	string	✅ Yes	The Invoice Reference Number to encrypt and embed in the QR code.
certificate	string	✅ Yes	X.509 certificate in PEM format (used for validation or signing, if needed).
publicKey	string	✅ Yes	RSA public key in PEM format used for encrypting the IRN.
size	number	❌ No	Size of the QR code in pixels (default: 200).
fgColor	string	❌ No	Foreground (QR pattern) color in HEX format (default: '#000000').
bgColor	string	❌ No	Background color in HEX format (default: '#FFFFFF').
logo	string	❌ No	Optional URL or local path to a logo image to embed at the center.
logoSizeRatio	number	❌ No	Ratio (0–1) of the logo size relative to the QR code size (default: 0.2).

Returns: Promise<EncryptionResult>

• encryptedBase64 (Buffer): Encrypted payload
• qrCodeDataUrl (string): QR code as base64 string
• qrCodeBuffer (Buffer): QR code as PNG buffer

decryptInvoice(options)

Decrypts encrypted invoice payload.

Parameters:

• options (Object)
  • invoice_schema (Buffer): Encrypted data buffer

Returns: Promise<Object> - Decrypted invoice data

---

🛠 Requirements

System Requirements

• Node.js: v16.0.0 or higher
• OpenSSL: Must be installed and available in your system PATH
• Operating System:
  • ✅ Linux (Ubuntu, CentOS, etc.)
  • ✅ macOS (Intel & Apple Silicon)
  • ✅ Windows (with WSL2 recommended for CLI)

Dependencies

The package automatically handles all required dependencies. No additional setup needed.

---

🚦 Environment Setup

Verify Prerequisites

1# Check Node.js version
2node --version  # Should be v16+
3
4# Check OpenSSL availability
5openssl version  # Should return OpenSSL version info
6
7# Check npm/yarn version
8npm --version
9yarn --version

For Windows Users

We recommend using WSL2 (Windows Subsystem for Linux) for the best CLI experience:

1# Install WSL2 (if not already installed)
2wsl --install
3
4# Or use Windows Terminal with PowerShell
5# Most features work on Windows, but WSL2 provides better compatibility

---

📋 Examples

Complete Example: E-Invoice Processing

Generate QR Code

1import { generateQRCode } from "firs-einvoicing";
2
3async function createQRCode() {
4  try {
5    const { encryptedBase64, qrCodeDataUrl, qrCodeBuffer } = await generateQRCode({
6// NOTE: You do not need to provide a timestamp manually. A timestamp is automatically generated at the time of processing.
7      irn: "IRN123-0FD6C95D-20250609",
8      certificate:
9        "bEF0V3FJbmo5cVZYbEdCblB4QVpjMG9HVWFrc29GM2hiYWFkYWMyODRBUT0=",
10      publicKey:
11        "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUlJQklqQU5CZ2txaGtpRzl3MEJBUUVGQ",
12      size: 300,
13      fgColor: "#000000",
14      bgColor: "#00FFFF",
15      logo: "https://example.com/logo.png",
16      logoSizeRatio: 0.2,
17    });
18    console.log("QR Code Buffer:", qrCodeBuffer);
19    console.log("Base64 QR Code:", qrCodeDataUrl);
20    console.log("Encrypted Base64:", encryptedBase64);
21
22  } catch (error) {
23    console.error("Error:", error.message);
24  }
25}
26
27createQRCode();

Decrypt e-invoice

1import { decryptInvoice } from "firs-einvoicing";
2
3async function decryptInvoicePayload() {
4  try {
5    // Decrypt encrypted payload
6    const encrypted = {
7      iv_hex: "4342576a6a65397a38394e6e73423478",
8      pub: "Zd22h6lAZeX667t9YKQ5Teua",
9      ciphertext: "Encrypted invoice",
10      api_key: "da5811ef-9c4e-42f1-ab4c-af654470c0ca",
11    };
12    const decryptedData = decryptInvoice(encrypted);
13
14    console.log("Decrypted Invoice:", decryptedData);
15  } catch (error) {
16    console.error("Error:", error.message);
17  }
18}
19
20decryptInvoicePayload();

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🏷️ Keywords

firs, e-invoicing, nigeria, tax, encryption, qr-code, irn, rsa, digital-signature, invoice, cli, nodejs