istd-xml-ts

Integration with Jordanian National E-Invoice System

Features

• Support for General Sales Tax
• NEW: Tunnel server support for IP-restricted environments
• NEW: Support for Income Tax invoices

Installation

npm install istd-xml-ts

Basic Usage

General Sales Tax Invoice (with VAT)

import {
  EGS,
  EGSUnitInfo,
  ISTDInvoice,
  ISTDInvoiceTypes,
  SalesTaxInvoiceLineItem,
  TaxType,
} from "istd-xml-ts";

// Create EGS instance
const egsInfo: EGSUnitInfo = {
  uuid: "your-uuid",
  vat_name: "Your Company Name",
  vat_number: "your-vat-number",
};

// Create sales tax line items
const line_item_1: SalesTaxInvoiceLineItem = {
  id: "1",
  name: "Product A",
  quantity: 3,
  tax_exclusive_price: 50,
  VAT_percent: 0.16,
  isZeroTax: false,
  discounts: [{ amount: 2, reason: "discount" }],
};

// Create sales tax invoice
const salesInvoice = new ISTDInvoice({
  props: {
    tax_type: TaxType.SalesTax,
    egs_info: egsInfo,
    invoice_counter_number: 1,
    invoice_type: ISTDInvoiceTypes.Invoice,
    cash_invoice: true,
    is_return: false,
    invoice_serial_number: "sales-serial-001",
    issue_date: "2024-11-12",
    line_items: [line_item_1],
    income_source_sequence: "17698220",
    note: "Sales Invoice",
    customer_info: {
      customer_type: "NIN",
      buyer_name: "Customer Name",
    },
  },
});

const egs = new EGS(egsInfo);
const invoice_xml = salesInvoice.getXML();
const invoice_xml_string = invoice_xml?.toString({ no_header: false }) || "";

// Report invoice
const result = await egs.reportInvoice(invoice_xml_string, clientId, secretKey);

Income Tax Invoice (without VAT)

import {
  EGS,
  EGSUnitInfo,
  ISTDInvoice,
  ISTDInvoiceTypes,
  IncomeTaxInvoiceLineItem,
  TaxType,
} from "istd-xml-ts";

// Create income tax line items (no VAT calculation)
const income_line_item: IncomeTaxInvoiceLineItem = {
  id: "1",
  name: "Consulting Services",
  quantity: 10,
  tax_exclusive_price: 100,
  discounts: [{ amount: 5, reason: "Early payment discount" }],
};

// Create income tax invoice
const incomeInvoice = new ISTDInvoice({
  props: {
    tax_type: TaxType.IncomeTax,
    egs_info: egsInfo,
    invoice_counter_number: 1,
    invoice_type: ISTDInvoiceTypes.Invoice,
    cash_invoice: true,
    is_return: false,
    invoice_serial_number: "income-serial-001",
    issue_date: "2024-11-12",
    line_items: [income_line_item],
    income_source_sequence: "17698220",
    note: "Income Tax Invoice",
    customer_info: {
      customer_type: "TN",
      buyer_name: "Business Client",
      tn_number: "1234567890",
    },
  },
});

const egs = new EGS(egsInfo);
const invoice_xml = incomeInvoice.getXML();
const invoice_xml_string = invoice_xml?.toString({ no_header: false }) || "";

// Report invoice
const result = await egs.reportInvoice(invoice_xml_string, clientId, secretKey);

Tunnel Server Support

For environments where the Jordan tax system only accepts requests from specific IP addresses, you can use the built-in tunnel server functionality:

import { EGS, TunnelConfig } from "istd-xml-ts";

// Configure tunnel
const tunnelConfig: TunnelConfig = {
  tunnelUrl: "http://your-tunnel-server:3000",
  tunnelSecret: "your-tunnel-secret",
};

// Use with tunnel
const egs = new EGS(egsInfo, tunnelConfig);
const result = await egs.reportInvoice(xmlString, clientId, secretKey);

For detailed tunnel setup instructions, see TUNNEL_GUIDE.md.

Supports

• General Sales Tax Invoices - with VAT calculation and tax categories
• Income Tax Invoices - without VAT calculation
• Return invoices (for both sales and income tax)
• Cash and credit invoices
• VAT calculations (for sales tax)
• Zero-rated and exempt tax categories
• Discount handling
• Type-safe invoice creation with TypeScript
• IP-restricted environments via tunnel server

Examples

See the /src/examples directory for complete examples:

• sales-invoice-example.ts - Complete sales tax invoice example
• income-invoice-example.ts - Complete income tax invoice example
• full.ts - Advanced example with tunnel configuration

Key Differences

Sales Tax Invoice

• Uses SalesTaxInvoiceLineItem with VAT_percent field
• Calculates VAT on each line item
• Supports zero-rated tax with vat_category.code (O or Z)
• InvoiceTypeCode: 012 (cash) or 022 (credit)

Income Tax Invoice

• Uses IncomeTaxInvoiceLineItem without VAT fields
• No VAT calculation performed
• InvoiceTypeCode: 011 (cash) or 021 (credit)