Challenge

Integrating with the Iranian tax system (Modian / “tax API version 1”) meant navigating strict requirements: authentication via fiscal ID, private keys, economic IDs; complex invoice formats; highly sensitive data; and communication only from allowed IPs. Many developers and companies had to build boilerplate and error-prone code to perform tasks like submitting invoices, checking status, or validating client economic codes.

Solution

We built taxapi, an npm/TypeScript package that wraps these operations. It provides clear, typed methods for:

• Getting a token (authentication)

• Fetching server info (public keys, etc.)

• Sending invoices in bulk or single (with retry logic)

• Querying invoice status by UID(s)

• Looking up client economic codes or fiscal IDs

• Utility functions like generating invoice serials

Everything is typed (TypeScript) for better developer experience. Security is accounted for: the package requires PEM private key, requires operations from approved IPs, and handles financial IDs and sensitive data carefully.

Implementation & Tech

• Language & Platform: Node.js + TypeScript, published on npm as taxapi. npm

• Architecture: The package is modular; it wraps the external tax API’s endpoints with high-level functions, handling tokens, retries, and error parsing.

• Dependencies and Distribution: Lightweight dependency footprint. MIT license. Designed for backend use only. npm

• Developer Experience: Includes type definitions, clear error handling, and utilities to abstract away repetitive tasks like serial generation. Good documentation in README. npm

Outcome

• Made integration with the tax API much easier for developers: less boilerplate, fewer errors.

• Reduced time-to-market for client or internal tools needing tax API functionality.

• Open-source exposure + credibility (thanks to npm, TypeScript, good docs).

• Possible reuse in your own product work (e.g. the Side App or others) since you have this as a solid base.