Billing API

A production-ready REST API for complete business billing management — built for freelancers and small businesses.

Built with Node.js · TypeScript · Express.js · Prisma · PostgreSQL · Swagger OAS 3.0

🌐 Live API: apibill.intlineconnect.com/api/docs

---

Overview

A complete billing backend that covers the full commercial cycle — from client onboarding to final receipt generation. Every document follows a strict, locked workflow to ensure business process integrity. Built with a modular Domain-Driven Design architecture and deployed in production on Render.

This API is actively used in production to manage real freelance clients and invoices.

---

Live Demo

The API is fully documented and deployed. You can explore all endpoints, authenticate, and test every route directly from the browser:

apibill.intlineconnect.com/api/docs

---

Features

Authentication

• Register, login, logout with JWT (access token + refresh token)
• HTTP-only cookie storage for refresh token
• Password reset and change password flows
• Profile management with logo upload (Cloudinary)

Client Management

• Create, update, delete clients with soft delete
• Paginated search with filters
• Full client history

Sales Workflow

• Quote creation with automatic tax and discount calculation
• Quote status machine: DRAFT → SENT → ACCEPTED / REJECTED
• Contract generation from an accepted quote
• Contract status machine with locked stage progression

Billing Workflow

• Invoice creation with line items, tax rate, discount, deposit, and due date
• Invoice status machine: DRAFT → SENT → PARTIALLY_PAID → PAID → OVERDUE
• Automatic overdue detection via scheduled cron job
• Payment recording with automatic invoice reconciliation
• Receipt generation after full payment

Document Generation

• PDF export for quotes, contracts, invoices, and receipts
• Each document rendered from a typed template
• PDF served via API endpoint

Audit Logs

• Every critical action tracked — who did what, when, and from which IP
• Full traceability across all modules

Locked Workflow Stages

Quote (ACCEPTED) → Contract → Invoice → Payment → Receipt

Each stage is locked — you cannot skip or reverse steps. This guarantees business process integrity.

---

Tech Stack

Runtime      : Node.js · TypeScript
Framework    : Express.js
ORM          : Prisma
Database     : PostgreSQL
Docs         : Swagger UI (OAS 3.0)
Auth         : JWT · HTTP-only cookies
Validation   : Zod
PDF          : Puppeteer · PDFKit
Storage      : Cloudinary · Local · S3 (configurable)
Scheduling   : Cron jobs (overdue invoice detection)
Logging      : Custom logger
Deployment   : Render

---

Architecture

This project follows a modular Domain-Driven Design approach. Each module is fully self-contained with its own routes, controller, service, repository, DTO, types, and domain logic.

src/
├── infrastructure/
│   ├── cloudinary/        # File upload service
│   ├── cron/              # Scheduled jobs (overdue invoices)
│   ├── database/          # Prisma client
│   ├── pdf/               # PDF generation engine + templates
│   │   └── templates/     # Quote, contract, invoice, receipt templates
│   └── logger/            # Application logger
│
├── modules/
│   ├── auth/              # Authentication & authorization
│   │   └── domain/        # Password hasher, token generator, auth policy
│   │
│   ├── clients/           # Client management
│   │   └── domain/        # Client validator
│   │
│   ├── audit/             # Audit log tracking
│   │
│   ├── sales/
│   │   ├── quotes/        # Quote management
│   │   │   └── domain/    # Calculator, state machine, number generator
│   │   └── contracts/     # Contract management
│   │       └── domain/    # State machine, number generator
│   │
│   └── billing/
│       ├── invoices/      # Invoice management
│       │   └── domain/    # Calculator, state machine, due date calculator
│       ├── payments/      # Payment recording & reconciliation
│       │   └── domain/    # Payment validator, reconciliation logic
│       └── receipts/      # Receipt generation
│           └── domain/    # Receipt number generator
│
├── shared/
│   ├── middlewares/       # Auth, validation, upload, error handling
│   ├── errors/            # Custom error classes and HTTP error codes
│   ├── audit/             # Shared audit service
│   ├── config/            # Environment configuration
│   └── utils/             # Date, currency, ID generator utilities
│
├── app.ts                 # Express app setup
├── routes.ts              # Global route registration
└── server.ts              # Server bootstrap

---

API Modules

Module	Endpoints	Access
Auth	Register, Login, Logout, Refresh, Reset password, Profile	Public / Auth
Clients	CRUD, soft delete, paginated search	Auth
Quotes	CRUD, status update, PDF export	Auth
Contracts	CRUD, status update, PDF export	Auth
Invoices	CRUD, status update, PDF export, payments	Auth
Payments	Create, list, get by ID, delete	Auth
Receipts	List, get by ID, PDF export	Auth
Audit Logs	List all logs, get by entity ID	Auth

Full API reference available at: apibill.intlineconnect.com/api/docs

---

Billing Workflow

1. Create a Client
         ↓
2. Create a Quote (DRAFT → SENT → ACCEPTED)
         ↓
3. Generate a Contract from accepted Quote
         ↓
4. Create an Invoice linked to the Contract
         ↓
5. Record Payments against the Invoice
         ↓
6. Receipt generated automatically on full payment

Each step is locked — the system validates the current state before allowing any transition.

---

Installation

1. Clone the repository

git clone https://github.com/IjayCoder/billing-api
cd billing-api

2. Install dependencies

npm install

3. Configure environment variables

cp .env.example .env

Edit .env:

DATABASE_URL=postgresql://user:password@localhost:5432/billing
JWT_SECRET=your_jwt_secret
JWT_REFRESH_SECRET=your_refresh_secret
CLOUDINARY_CLOUD_NAME=your_cloud_name
CLOUDINARY_API_KEY=your_api_key
CLOUDINARY_API_SECRET=your_api_secret
PORT=5000
CLIENT=your_cron_client_secret

4. Run database migrations

npx prisma migrate dev

5. Start the server

npm run dev

6. Open Swagger UI

http://localhost:5000/api/docs

---

Testing

The project includes unit, integration, and end-to-end test files structured per module.

npm run test          # Run all tests
npm run test:unit     # Unit tests only
npm run test:e2e      # End-to-end tests

Unit tests are currently in progress. The API is fully functional and manually tested via Swagger UI in production.

---

Deployment

The API is deployed on Render and accessible in production:

Base URL  : https://apibill.intlineconnect.com/api/v1
Swagger   : https://apibill.intlineconnect.com/api/docs

---

Author

Yaji Nonfon — Freelance Backend Developer

• Portfolio: yajidev.intlineconnect.com
• LinkedIn: linkedin.com/in/yajinonfon
• Email: sonagnonyaji@gmail.com
• WhatsApp: +233 532 606 416