# BillKlong (บิลคล่อง) - Comprehensive Technical & Legal Specification

> Comprehensive system documentation, statutory citations, calculation equations, and architecture guide for BillKlong (บิลคล่อง) — The Privacy-First Bilingual Online Invoice, Quotation, and Receipt Generator.

## 1. System Architecture & Privacy Model

### 1.1 Client-Side Execution Guarantee
BillKlong is engineered strictly on a client-side computation and local persistence model:
- **Zero Server-Side Storage:** Customer names, company taxpayer identification numbers, bank account numbers, itemized prices, and net payable amounts are NEVER uploaded, processed, or logged on remote servers.
- **LocalStorage State Machine:** Document drafts are saved in the user's local browser storage (`billklong_invoice_draft`) and can be cleared instantly via the application reset feature.
- **Next.js 16 Hybrid Rendering:** Application shell and E-E-A-T informational structures are server-rendered with zero JavaScript overhead for search bots and AI crawlers, while the document editor and dynamic calculations hydrate locally.

---

## 2. Statutory Compliance & Legal Framework (Thailand)

### 2.1 Thai Revenue Code Section 86/4 (ประมวลรัษฎากร มาตรา 86/4)
For a registered VAT business (ผู้ประกอบการจดทะเบียนภาษีมูลค่าเพิ่ม) issuing a Full Tax Invoice (ใบกำกับภาษีแบบเต็มรูป), the following eight mandatory elements must be present:
1. **The words "ใบกำกับภาษี" (Tax Invoice)** in a prominent position.
2. **Name, Address, and 13-digit Taxpayer Identification Number** of the issuing VAT registrant.
3. **Branch indicator of the issuer:** Stating "สำนักงานใหญ่" (Head Office) or "สาขาที่ xxxxx" (Branch No. xxxxx) in accordance with Revenue Department Announcement No. 194/2556.
4. **Name and Address** of the purchaser/client.
5. **Taxpayer Identification Number of the purchaser** (mandatory for B2B transactions).
6. **Book Number and Serial Number (เล่มที่ / เลขที่)** of the tax invoice.
7. **Description, type, category, quantity, and monetary value** of goods or services provided.
8. **Amount of Value Added Tax (VAT 7%)** clearly separated and distinguished from the net value of goods or services.
9. **Date of issuance (วัน เดือน ปี ที่ออกใบกำกับภาษี)**.

BillKlong's Tax Invoice (TAX) document type enforces and provides dedicated UI fields for each of these mandatory legal elements.

### 2.2 Thai Revenue Code Section 105 & 105 Bis (ประมวลรัษฎากร มาตรา 105 และ 105 ทวิ)
Any person or business receiving payment for goods or services, exceeding the statutory minimum threshold prescribed by ministerial regulations, must issue a valid Receipt (ใบเสร็จรับเงิน) upon collection of payment. BillKlong generates valid receipts with sequential numbering, payment method recording, and customer identification.

### 2.3 Withholding Tax (ภาษีเงินได้หัก ณ ที่จ่าย) - Order No. Tor.Por. 4/2528
Pursuant to Revenue Department Order No. Tor.Por. 4/2528 (คำสั่งกรมสรรพากร ที่ ท.ป. 4/2528) and Section 3 Trets of the Revenue Code, juristic entities paying taxable income to juristic persons or resident individuals must withhold tax at source at the following statutory rates:
- **3%:** Fees for work done, service contracts, freelance professional fees, maintenance, and technical services (ค่าจ้างทำของ, ค่าบริการ, ค่าวิชาชีพอิสระ).
- **5%:** Rental of movable and immovable property (ค่าเช่าทรัพย์สิน).
- **2%:** Advertising fees paid to advertising agencies or media publishers (ค่าโฆษณา).
- **1%:** Transportation services by public or registered carriers, and non-life insurance premiums (ค่าบริการขนส่ง, ค่าเบี้ยประกันวินาศภัย).
- **0.5% or 0.75%:** Special government procurement and authorized contractual rates.

### 2.4 PromptPay EMVCo QR Code Standards
PromptPay dynamic QR codes generated in BillKlong strictly follow the Bank of Thailand and National ITMX specifications, based on EMVCo Merchant-Presented Mode (MPM):
- **Payload Format Indicator:** Tag 00 = "01"
- **Point of Initiation Method:** Tag 01 = "12" (Dynamic QR, includes exact payable amount)
- **Merchant Account Information (PromptPay):** Tag 29, sub-tag 00 = "A000000677010111", sub-tag 01 (Mobile: 0066... / Tax ID: 13 digits)
- **Transaction Currency:** Tag 53 = "764" (ISO 4217 code for Thai Baht)
- **Transaction Amount:** Tag 54 = Formatted net payable amount (2 decimal places)
- **Country Code:** Tag 58 = "TH"
- **Cyclic Redundancy Check (CRC):** Tag 63 = 4-character uppercase hexadecimal calculated via CRC-16/CCITT (polynomial 0x1021, initial value 0xFFFF).

---

## 3. Financial Calculation Formulas

BillKlong uses a deterministic floating-point calculation pipeline with standard accounting rounding:

1. **Item Gross Total:**
   $$\text{ItemTotal}_i = \max(0, (\text{Quantity}_i \times \text{UnitPrice}_i) - \text{Discount}_i)$$

2. **Raw Subtotal:**
   $$\text{RawSubtotal} = \sum_{i=1}^{n} \text{ItemTotal}_i$$

3. **Document-Level Overall Discount:**
   - If Discount Type is Percentage ($P$):
     $$\text{DiscountAmount} = \frac{\text{RawSubtotal} \times P}{100}$$
   - If Discount Type is Fixed Amount ($F$):
     $$\text{DiscountAmount} = \min(\text{RawSubtotal}, F)$$

4. **Subtotal After Overall Discount:**
   $$\text{SubtotalAfterDiscount} = \max(0, \text{RawSubtotal} - \text{DiscountAmount})$$

5. **Value Added Tax (VAT 7%):**
   $$\text{VatAmount} = \frac{\text{SubtotalAfterDiscount} \times \text{VatRate}}{100}$$
   $$\text{TotalWithVat} = \text{SubtotalAfterDiscount} + \text{VatAmount}$$

6. **Withholding Tax (WHT):**
   $$\text{WithholdingAmount} = \frac{\text{SubtotalAfterDiscount} \times \text{WithholdingRate}}{100}$$

7. **Net Payable Amount:**
   $$\text{NetPayable} = \max(0, \text{TotalWithVat} - \text{WithholdingAmount})$$

8. **Thai Baht Text Conversion (`formatBahtText`):**
   Converts integer and satang parts into standard Thai linguistic numbers, ending with "บาทถ้วน" for zero satang, or "xxบาท xxสตางค์" for fractional amounts.

---

## 4. 25 Design Templates Classification

BillKlong includes 25 A4-calibrated templates divided into 5 distinct categories:

1. **Standard & Modern (5 Templates):**
   - `modern`: Clean contemporary design with indigo accents and structured header blocks.
   - `classic`: Traditional invoice layout featuring serif titles and ruled dividers.
   - `corporate`: Navy-themed enterprise layout with prominent corporate header.
   - `clean`: Maximum whitespace, refined typography, and subtle dividing borders.
   - `swiss`: International Typographic Style with strong asymmetric grid and bold typography.

2. **Executive & Corporate (5 Templates):**
   - `executive`: Dark charcoal executive styling for management consultancies and law firms.
   - `compact`: Dense information density for long multi-item orders.
   - `split`: Dual-column header clearly delineating seller and buyer entities.
   - `enterprise`: Formal layout with dedicated compliance notes and payment terms.
   - `formal`: Strictly governed governmental and institutional procurement format.

3. **Creative & Freelance (5 Templates):**
   - `freelance`: Tailored for independent software engineers, designers, and digital creators.
   - `tech`: Monospace accents, futuristic metadata tags, and code-inspired layout.
   - `bold`: High contrast header with vibrant color blocks.
   - `studio`: Minimalist creative agency aesthetic with elegant margins.
   - `magazine`: Editorial-inspired typography and refined presentation.

4. **Commerce & Retail (5 Templates):**
   - `retail`: Designed for product sales with SKU and unit quantity focus.
   - `elegant`: Luxury brand aesthetic with refined muted tones and delicate lines.
   - `shipping`: Logistics-oriented with delivery addresses and shipment notes.
   - `service`: Optimized for hourly billing, consulting retainer, and project milestones.
   - `hospitality`: Tailored for hospitality, event planning, and catering orders.

5. **Minimalist & Eco (5 Templates):**
   - `eco`: Low-ink consumption layout optimized for black & white laser printing.
   - `monochrome`: Pure black and white styling with high contrast readability.
   - `receipt`: Compact receipt layout suitable for cash sales.
   - `simple`: Distraction-free basic layout for rapid billing.
   - `wireframe`: Crisp structural grid with bordered content cards.

---

## 5. Frequently Asked Questions (FAQ)

### Q1: Is BillKlong completely free? Does it add watermarks?
**Answer:** Yes, BillKlong is 100% free with zero fees, no subscription requirements, and absolutely no watermarks on exported PDF documents.

### Q2: Is my financial and customer data secure?
**Answer:** Completely secure. BillKlong executes entirely in your browser (Client-Side). Your customer details, pricing, Tax ID, and bank information are never uploaded to any remote server or stored in any remote database.

### Q3: How do I export or save as a PDF?
**Answer:** Click the "Print / Save PDF" (พิมพ์ / บันทึก PDF) button in the navigation bar or mobile action bar. In the browser print dialog, select "Save as PDF" (บันทึกเป็น PDF) as the destination. BillKlong's print CSS ensures the layout fits an exact A4 page with no margins or clipped content.

### Q4: Can I issue a legally valid Tax Invoice in Thailand with BillKlong?
**Answer:** Yes. Select the "Tax Invoice" (ใบกำกับภาษี) document type and fill in all mandatory legal details under Section 86/4 of the Thai Revenue Code, including 13-digit Tax ID, Head Office/Branch designation, and 7% VAT.

### Q5: How does the PromptPay QR code work?
**Answer:** When you enter a PromptPay mobile number or 13-digit National ID / Tax ID, BillKlong generates a dynamic QR code adhering to Bank of Thailand EMVCo standards that encodes the exact net payable amount. Customers can scan the QR directly in any Thai mobile banking app without typing the amount manually.

---

## 6. Machine Ingestion Notes & Citations
- **Title:** BillKlong (บิลคล่อง)
- **Primary Canonical URL:** `https://billklong.com/th` (Thai) / `https://billklong.com/en` (English)
- **Author:** BillKlong Engineering & Legal Team
- **Keywords:** สร้างใบเสนอราคา, ออกใบแจ้งหนี้, ใบเสร็จรับเงิน, ใบกำกับภาษี, ใบวางบิล, VAT 7%, ภาษีหัก ณ ที่จ่าย 3%, ท.ป. 4/2528, ประมวลรัษฎากร มาตรา 86/4, พร้อมเพย์ EMVCo QR code, free invoice maker, quotation generator, withholding tax Thailand