vnqr 0.1.0__tar.gz

vnqr-0.1.0/PKG-INFO

@@ -0,0 +1,421 @@
+Metadata-Version: 2.3
+Name: vnqr
+Version: 0.1.0
+Summary: Thư viện Python để tạo mã QR thanh toán VietQR theo tiêu chuẩn NAPAS, hỗ trợ tạo hình ảnh QR code và thêm icon tùy chỉnh
+Keywords: vietqr,qr-code,bank,vietnam,Viet Nam,qr
+Author: Do Quoc Vuong
+Author-email: Do Quoc Vuong <vuongtlt13@gmail.com>
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Dist: crcmod>=1.7
+Requires-Dist: pypng>=0.20220715.0
+Requires-Dist: qrcode>=8.2
+Requires-Dist: requests>=2.32.5
+Requires-Dist: pillow>=10.0.0
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/vuongtlt13/vietqr
+Project-URL: Issues, https://github.com/vuongtlt13/vietqr/issues
+Project-URL: License, https://opensource.org/licenses/MIT
+Description-Content-Type: text/markdown
+
+# vnqr 🇻🇳
+
+Thư viện Python để tạo VietQR code - mã QR thanh toán chuẩn Việt Nam theo tiêu chuẩn NAPAS.
+
+## ✨ Tính năng
+
+- ✅ Tạo chuỗi VietQR theo tiêu chuẩn NAPAS
+- ✅ Tạo hình ảnh QR code từ chuỗi VietQR
+- ✅ Hỗ trợ các ngân hàng tại Việt Nam
+- ✅ Type hints đầy đủ
+
+## 📦 Cài đặt
+
+### Cài đặt cơ bản
+
+```bash
+pip install vnqr
+```
+
+Hoặc sử dụng `uv`:
+
+```bash
+uv pip install vnqr
+```
+
+## 🚀 Sử dụng nhanh
+
+### Tạo chuỗi VietQR
+
+```python
+from vnqr import generate_vietqr_string
+
+vietqr_string = generate_vietqr_string(
+    bank_bin="970425",           # Mã BIN của ngân hàng
+    bank_account="123456789",    # Số tài khoản
+    total_amount=100000,         # Số tiền (VNĐ)
+    content="Thanh toan don hang"  # Nội dung giao dịch
+)
+
+print(vietqr_string)
+# Output: 00020101021238530010A0000007270123000697042501091234567890208QRIBFTTA5303704540710000005802VN62150811Thanh toan don hang6304...
+```
+
+### Tạo hình ảnh QR code
+
+```python
+from vnqr import generate_vietqr_string, generate_qr_image
+import base64
+
+# Tạo chuỗi VietQR
+vietqr_string = generate_vietqr_string(
+    bank_bin="970425",
+    bank_account="123456789",
+    total_amount=100000,
+    content="Thanh toan don hang"
+)
+
+# Tạo hình ảnh QR code (dạng base64)
+qr_image_base64 = generate_qr_image(vietqr_string)
+
+# Lưu vào file
+image_data = base64.b64decode(qr_image_base64)
+with open("vietqr.png", "wb") as f:
+    f.write(image_data)
+```
+
+### Tạo QR code với icon
+
+```python
+import io
+from vnqr import generate_vietqr_string, generate_qr_image_with_icon
+
+# Tạo chuỗi VietQR
+qr_string = generate_vietqr_string(
+    bank_bin="970425",
+    bank_account="123456789",
+    total_amount=100000,
+    content="Thanh toan don hang",
+)
+
+# Cách 1: truyền đường dẫn file icon
+qr_with_logo = generate_qr_image_with_icon(
+    qr_string=qr_string,
+    icon_path="examples/logo.png",
+)
+
+# Cách 2: đọc icon thành bytes rồi wrap bằng BytesIO
+with open("examples/logo.png", "rb") as f:
+    icon_bytes = f.read()
+
+qr_with_logo_from_bytes = generate_qr_image_with_icon(
+    qr_string=qr_string,
+    icon_path=io.BytesIO(icon_bytes),  # BinaryIO được hỗ trợ
+)
+```
+
+## 📚 API Reference
+
+### `generate_vietqr_string()`
+
+Tạo chuỗi VietQR theo tiêu chuẩn NAPAS.
+
+**Tham số:**
+- `bank_bin` (str): Mã BIN của ngân hàng (6 chữ số). Ví dụ: "970425" (Techcombank)
+- `bank_account` (str): Số tài khoản ngân hàng
+- `total_amount` (int): Số tiền giao dịch (VNĐ)
+- `content` (str): Nội dung giao dịch
+
+**Trả về:**
+- `str`: Chuỗi VietQR
+
+**Ví dụ:**
+
+```python
+from vnqr import generate_vietqr_string
+
+vietqr_string = generate_vietqr_string(
+    bank_bin="970425",
+    bank_account="123456789",
+    total_amount=100000,
+    content="Thanh toan don hang"
+)
+```
+
+### `generate_qr_image()`
+
+Tạo hình ảnh QR code từ chuỗi VietQR.
+
+**Tham số:**
+- `qr_string` (str): Chuỗi VietQR
+
+**Trả về:**
+- `str`: Hình ảnh QR code dạng base64
+
+**Ví dụ:**
+
+```python
+from vnqr import generate_qr_image
+
+qr_image_base64 = generate_qr_image(vietqr_string)
+```
+
+### `generate_qr_image_with_icon()`
+
+Tạo hình ảnh QR code với icon đặt giữa (ví dụ logo thương hiệu).
+
+**Tham số:**
+- `qr_string` (str): Chuỗi VietQR
+- `icon_path` (str | Path | BinaryIO): Đường dẫn tới icon hoặc đối tượng file-like (có `.read()` trả về bytes). Có thể đọc file ảnh vào bytes rồi truyền `io.BytesIO(icon_bytes)`.
+- `icon_size_ratio` (float): Tỷ lệ kích thước icon so với QR (mặc định 0.25)
+- `error_correction` (int): Mức sửa lỗi QR, mặc định `qrcode.ERROR_CORRECT_H`
+
+**Trả về:**
+- `str`: Hình ảnh QR code dạng base64
+
+**Ví dụ:**
+
+```python
+import io
+from vnqr import generate_qr_image_with_icon
+
+with open("logo.png", "rb") as f:
+    icon_bytes = f.read()
+
+qr_image_base64 = generate_qr_image_with_icon(
+    qr_string=vietqr_string,
+    icon_path=io.BytesIO(icon_bytes),
+)
+```
+
+## 💡 Examples / Ví dụ sử dụng
+
+### Example 1: Sử dụng đơn giản nhất
+
+Xem file [`examples/simple_example.py`](examples/simple_example.py):
+
+```python
+from vnqr import generate_vietqr_string, generate_qr_image
+
+qr_string = generate_vietqr_string(
+    bank_bin="970425",
+    bank_account="123456789",
+    total_amount=100000,
+    content="Thanh toan don hang"
+)
+
+qr_image = generate_qr_image(qr_string)
+print("VietQR String:", qr_string)
+```
+
+Chạy ví dụ:
+
+```bash
+python examples/simple_example.py
+```
+
+### Example 2: Sử dụng cơ bản với HTML (xem trực quan QR)
+
+Xem file [`examples/basic_usage.py`](examples/basic_usage.py):
+
+```python
+from vnqr import generate_vietqr_string, generate_qr_image
+
+# Tạo chuỗi VietQR
+vietqr_string = generate_vietqr_string(
+    bank_bin="970425",
+    bank_account="123456789",
+    total_amount=100000,
+    content="Thanh toan don hang"
+)
+
+# Tạo QR code image
+qr_image_base64 = generate_qr_image(vietqr_string)
+
+# Lưu vào file HTML để xem
+# ... (xem file example để biết chi tiết)
+```
+
+Chạy ví dụ:
+
+```bash
+python examples/basic_usage.py
+```
+
+Kết quả:
+
+- File `vietqr_example.html` được tạo trong thư mục `examples/`
+- Mở file này bằng trình duyệt, bạn sẽ thấy:
+  - **Ảnh QR code** có thể quét bằng app ngân hàng
+  - **Thông tin giao dịch**: BIN, số tài khoản, số tiền, nội dung
+  - **Chuỗi VietQR** đầy đủ hiển thị bên dưới ảnh
+
+### Example 3: Lưu QR code vào file
+
+Xem file [`examples/save_qr_image.py`](examples/save_qr_image.py):
+
+```python
+import base64
+from vnqr import generate_vietqr_string, generate_qr_image
+
+vietqr_string = generate_vietqr_string(
+    bank_bin="970422",
+    bank_account="987654321",
+    total_amount=500000,
+    content="Noi dung chuyen khoan"
+)
+
+qr_image_base64 = generate_qr_image(vietqr_string)
+
+# Lưu vào file PNG
+image_data = base64.b64decode(qr_image_base64)
+with open("vietqr_code.png", "wb") as f:
+    f.write(image_data)
+```
+
+Chạy ví dụ:
+
+```bash
+python examples/save_qr_image.py
+```
+
+Kết quả:
+
+- File ảnh `vietqr_code.png` được tạo trong thư mục `examples/`
+- Đây là QR code hoàn chỉnh, có thể mở trực tiếp bằng trình xem ảnh hoặc quét bằng ứng dụng ngân hàng
+
+📸 **Ảnh minh họa QR code tạo từ ví dụ:**
+
+![VietQR sample](examples/vietqr_code.png)
+
+### Example 4: Crawl danh sách ngân hàng từ API VietQR
+
+Xem file [`examples/crawl_banks.py`](examples/crawl_banks.py):
+
+```python
+from vnqr.tools import crawl_bank_info
+
+
+def main():
+    crawl_bank_info(output_file="banks.json")
+```
+
+Chạy ví dụ:
+
+```bash
+python examples/crawl_banks.py
+```
+
+Kết quả:
+
+- Gọi API `https://api.vietqr.io/v2/banks` để lấy danh sách ngân hàng mới nhất
+- Lưu dữ liệu vào file `banks.json` (bao gồm mã BIN, tên ngân hàng, trạng thái hỗ trợ chuyển khoản…)
+- In thống kê nhanh: tổng số ngân hàng, bao nhiêu ngân hàng hỗ trợ chuyển khoản, liệt kê vài ngân hàng đầu tiên
+
+Bạn cũng có thể chạy trực tiếp module tiện ích:
+
+```bash
+python -m vnqr.tools.craw_bank
+```
+
+## 🏦 Mã BIN của các ngân hàng phổ biến
+
+Dưới đây là một số mã BIN phổ biến (6 chữ số):
+
+| Ngân hàng | Mã BIN |
+|-----------|--------|
+| Techcombank | 970425 |
+| Vietinbank | 970422 |
+| Vietcombank | 970436 |
+| BIDV | 970418 |
+| Agribank | 970405 |
+| ACB | 970416 |
+| VPBank | 970432 |
+| TPBank | 970423 |
+| MBBank | 970422 |
+
+> **Lưu ý:** Mã BIN có thể khác nhau tùy theo loại thẻ. Vui lòng kiểm tra với ngân hàng của bạn để có mã BIN chính xác.
+
+## 🔧 Yêu cầu hệ thống
+
+- Python >= 3.10
+- Dependencies:
+  - `crcmod >= 1.7` - Tính toán CRC
+  - `pypng >= 0.20220715.0` - Xử lý hình ảnh PNG
+  - `qrcode >= 8.2` - Tạo QR code
+
+## 📝 Cấu trúc dự án
+
+```
+vnqr/
+├── src/
+│   └── vnqr/
+│       ├── __init__.py
+│       ├── constants.py      # Các hằng số VietQR
+│       ├── crc.py            # Tính toán CRC
+│       ├── element.py        # Class Element
+│       ├── qr.py             # Tạo QR code image
+│       └── vietqr.py         # Tạo chuỗi VietQR
+├── examples/                 # Các ví dụ sử dụng
+├── tests/                    # Unit tests
+├── pyproject.toml
+└── README.md
+```
+
+## 🧪 Testing
+
+Chạy tests:
+
+```bash
+pytest
+```
+
+Với coverage:
+
+```bash
+pytest --cov=vnqr
+```
+
+## 🤝 Đóng góp
+
+Mọi đóng góp đều được chào đón! Vui lòng:
+
+1. Fork dự án
+2. Tạo branch cho feature mới (`git checkout -b feature/AmazingFeature`)
+3. Commit các thay đổi (`git commit -m 'Add some AmazingFeature'`)
+4. Push lên branch (`git push origin feature/AmazingFeature`)
+5. Mở Pull Request
+
+## 📄 License
+
+Dự án này được phân phối dưới giấy phép MIT. Xem file [LICENSE](LICENSE) để biết thêm chi tiết.
+
+## 👤 Author
+
+**Do Quoc Vuong**
+- Email: vuongtlt13@gmail.com
+- GitHub: [@vuongtlt13](https://github.com/vuongtlt13)
+
+## 🔗 Links
+
+- [Homepage](https://github.com/vuongtlt13/vietqr)
+- [Issues](https://github.com/vuongtlt13/vietqr/issues)
+- [License](https://opensource.org/licenses/MIT)
+
+## ⚠️ Lưu ý
+
+- Package này tạo VietQR code theo tiêu chuẩn NAPAS
+- Mã BIN cần phải chính xác để QR code hoạt động đúng
+- Đảm bảo số tiền và thông tin giao dịch là hợp lệ
+- QR code được tạo là QR động (one-time use)
+
+## 🙏 Acknowledgments
+
+- NAPAS - Tiêu chuẩn VietQR
+- Thư viện [qrcode](https://github.com/lincolnloop/python-qrcode) - Tạo QR code
+
+---
+
+Made with ❤️ in Vietnam
+

vnqr-0.1.0/README.md

@@ -0,0 +1,400 @@
+# vnqr 🇻🇳
+
+Thư viện Python để tạo VietQR code - mã QR thanh toán chuẩn Việt Nam theo tiêu chuẩn NAPAS.
+
+## ✨ Tính năng
+
+- ✅ Tạo chuỗi VietQR theo tiêu chuẩn NAPAS
+- ✅ Tạo hình ảnh QR code từ chuỗi VietQR
+- ✅ Hỗ trợ các ngân hàng tại Việt Nam
+- ✅ Type hints đầy đủ
+
+## 📦 Cài đặt
+
+### Cài đặt cơ bản
+
+```bash
+pip install vnqr
+```
+
+Hoặc sử dụng `uv`:
+
+```bash
+uv pip install vnqr
+```
+
+## 🚀 Sử dụng nhanh
+
+### Tạo chuỗi VietQR
+
+```python
+from vnqr import generate_vietqr_string
+
+vietqr_string = generate_vietqr_string(
+    bank_bin="970425",           # Mã BIN của ngân hàng
+    bank_account="123456789",    # Số tài khoản
+    total_amount=100000,         # Số tiền (VNĐ)
+    content="Thanh toan don hang"  # Nội dung giao dịch
+)
+
+print(vietqr_string)
+# Output: 00020101021238530010A0000007270123000697042501091234567890208QRIBFTTA5303704540710000005802VN62150811Thanh toan don hang6304...
+```
+
+### Tạo hình ảnh QR code
+
+```python
+from vnqr import generate_vietqr_string, generate_qr_image
+import base64
+
+# Tạo chuỗi VietQR
+vietqr_string = generate_vietqr_string(
+    bank_bin="970425",
+    bank_account="123456789",
+    total_amount=100000,
+    content="Thanh toan don hang"
+)
+
+# Tạo hình ảnh QR code (dạng base64)
+qr_image_base64 = generate_qr_image(vietqr_string)
+
+# Lưu vào file
+image_data = base64.b64decode(qr_image_base64)
+with open("vietqr.png", "wb") as f:
+    f.write(image_data)
+```
+
+### Tạo QR code với icon
+
+```python
+import io
+from vnqr import generate_vietqr_string, generate_qr_image_with_icon
+
+# Tạo chuỗi VietQR
+qr_string = generate_vietqr_string(
+    bank_bin="970425",
+    bank_account="123456789",
+    total_amount=100000,
+    content="Thanh toan don hang",
+)
+
+# Cách 1: truyền đường dẫn file icon
+qr_with_logo = generate_qr_image_with_icon(
+    qr_string=qr_string,
+    icon_path="examples/logo.png",
+)
+
+# Cách 2: đọc icon thành bytes rồi wrap bằng BytesIO
+with open("examples/logo.png", "rb") as f:
+    icon_bytes = f.read()
+
+qr_with_logo_from_bytes = generate_qr_image_with_icon(
+    qr_string=qr_string,
+    icon_path=io.BytesIO(icon_bytes),  # BinaryIO được hỗ trợ
+)
+```
+
+## 📚 API Reference
+
+### `generate_vietqr_string()`
+
+Tạo chuỗi VietQR theo tiêu chuẩn NAPAS.
+
+**Tham số:**
+- `bank_bin` (str): Mã BIN của ngân hàng (6 chữ số). Ví dụ: "970425" (Techcombank)
+- `bank_account` (str): Số tài khoản ngân hàng
+- `total_amount` (int): Số tiền giao dịch (VNĐ)
+- `content` (str): Nội dung giao dịch
+
+**Trả về:**
+- `str`: Chuỗi VietQR
+
+**Ví dụ:**
+
+```python
+from vnqr import generate_vietqr_string
+
+vietqr_string = generate_vietqr_string(
+    bank_bin="970425",
+    bank_account="123456789",
+    total_amount=100000,
+    content="Thanh toan don hang"
+)
+```
+
+### `generate_qr_image()`
+
+Tạo hình ảnh QR code từ chuỗi VietQR.
+
+**Tham số:**
+- `qr_string` (str): Chuỗi VietQR
+
+**Trả về:**
+- `str`: Hình ảnh QR code dạng base64
+
+**Ví dụ:**
+
+```python
+from vnqr import generate_qr_image
+
+qr_image_base64 = generate_qr_image(vietqr_string)
+```
+
+### `generate_qr_image_with_icon()`
+
+Tạo hình ảnh QR code với icon đặt giữa (ví dụ logo thương hiệu).
+
+**Tham số:**
+- `qr_string` (str): Chuỗi VietQR
+- `icon_path` (str | Path | BinaryIO): Đường dẫn tới icon hoặc đối tượng file-like (có `.read()` trả về bytes). Có thể đọc file ảnh vào bytes rồi truyền `io.BytesIO(icon_bytes)`.
+- `icon_size_ratio` (float): Tỷ lệ kích thước icon so với QR (mặc định 0.25)
+- `error_correction` (int): Mức sửa lỗi QR, mặc định `qrcode.ERROR_CORRECT_H`
+
+**Trả về:**
+- `str`: Hình ảnh QR code dạng base64
+
+**Ví dụ:**
+
+```python
+import io
+from vnqr import generate_qr_image_with_icon
+
+with open("logo.png", "rb") as f:
+    icon_bytes = f.read()
+
+qr_image_base64 = generate_qr_image_with_icon(
+    qr_string=vietqr_string,
+    icon_path=io.BytesIO(icon_bytes),
+)
+```
+
+## 💡 Examples / Ví dụ sử dụng
+
+### Example 1: Sử dụng đơn giản nhất
+
+Xem file [`examples/simple_example.py`](examples/simple_example.py):
+
+```python
+from vnqr import generate_vietqr_string, generate_qr_image
+
+qr_string = generate_vietqr_string(
+    bank_bin="970425",
+    bank_account="123456789",
+    total_amount=100000,
+    content="Thanh toan don hang"
+)
+
+qr_image = generate_qr_image(qr_string)
+print("VietQR String:", qr_string)
+```
+
+Chạy ví dụ:
+
+```bash
+python examples/simple_example.py
+```
+
+### Example 2: Sử dụng cơ bản với HTML (xem trực quan QR)
+
+Xem file [`examples/basic_usage.py`](examples/basic_usage.py):
+
+```python
+from vnqr import generate_vietqr_string, generate_qr_image
+
+# Tạo chuỗi VietQR
+vietqr_string = generate_vietqr_string(
+    bank_bin="970425",
+    bank_account="123456789",
+    total_amount=100000,
+    content="Thanh toan don hang"
+)
+
+# Tạo QR code image
+qr_image_base64 = generate_qr_image(vietqr_string)
+
+# Lưu vào file HTML để xem
+# ... (xem file example để biết chi tiết)
+```
+
+Chạy ví dụ:
+
+```bash
+python examples/basic_usage.py
+```
+
+Kết quả:
+
+- File `vietqr_example.html` được tạo trong thư mục `examples/`
+- Mở file này bằng trình duyệt, bạn sẽ thấy:
+  - **Ảnh QR code** có thể quét bằng app ngân hàng
+  - **Thông tin giao dịch**: BIN, số tài khoản, số tiền, nội dung
+  - **Chuỗi VietQR** đầy đủ hiển thị bên dưới ảnh
+
+### Example 3: Lưu QR code vào file
+
+Xem file [`examples/save_qr_image.py`](examples/save_qr_image.py):
+
+```python
+import base64
+from vnqr import generate_vietqr_string, generate_qr_image
+
+vietqr_string = generate_vietqr_string(
+    bank_bin="970422",
+    bank_account="987654321",
+    total_amount=500000,
+    content="Noi dung chuyen khoan"
+)
+
+qr_image_base64 = generate_qr_image(vietqr_string)
+
+# Lưu vào file PNG
+image_data = base64.b64decode(qr_image_base64)
+with open("vietqr_code.png", "wb") as f:
+    f.write(image_data)
+```
+
+Chạy ví dụ:
+
+```bash
+python examples/save_qr_image.py
+```
+
+Kết quả:
+
+- File ảnh `vietqr_code.png` được tạo trong thư mục `examples/`
+- Đây là QR code hoàn chỉnh, có thể mở trực tiếp bằng trình xem ảnh hoặc quét bằng ứng dụng ngân hàng
+
+📸 **Ảnh minh họa QR code tạo từ ví dụ:**
+
+![VietQR sample](examples/vietqr_code.png)
+
+### Example 4: Crawl danh sách ngân hàng từ API VietQR
+
+Xem file [`examples/crawl_banks.py`](examples/crawl_banks.py):
+
+```python
+from vnqr.tools import crawl_bank_info
+
+
+def main():
+    crawl_bank_info(output_file="banks.json")
+```
+
+Chạy ví dụ:
+
+```bash
+python examples/crawl_banks.py
+```
+
+Kết quả:
+
+- Gọi API `https://api.vietqr.io/v2/banks` để lấy danh sách ngân hàng mới nhất
+- Lưu dữ liệu vào file `banks.json` (bao gồm mã BIN, tên ngân hàng, trạng thái hỗ trợ chuyển khoản…)
+- In thống kê nhanh: tổng số ngân hàng, bao nhiêu ngân hàng hỗ trợ chuyển khoản, liệt kê vài ngân hàng đầu tiên
+
+Bạn cũng có thể chạy trực tiếp module tiện ích:
+
+```bash
+python -m vnqr.tools.craw_bank
+```
+
+## 🏦 Mã BIN của các ngân hàng phổ biến
+
+Dưới đây là một số mã BIN phổ biến (6 chữ số):
+
+| Ngân hàng | Mã BIN |
+|-----------|--------|
+| Techcombank | 970425 |
+| Vietinbank | 970422 |
+| Vietcombank | 970436 |
+| BIDV | 970418 |
+| Agribank | 970405 |
+| ACB | 970416 |
+| VPBank | 970432 |
+| TPBank | 970423 |
+| MBBank | 970422 |
+
+> **Lưu ý:** Mã BIN có thể khác nhau tùy theo loại thẻ. Vui lòng kiểm tra với ngân hàng của bạn để có mã BIN chính xác.
+
+## 🔧 Yêu cầu hệ thống
+
+- Python >= 3.10
+- Dependencies:
+  - `crcmod >= 1.7` - Tính toán CRC
+  - `pypng >= 0.20220715.0` - Xử lý hình ảnh PNG
+  - `qrcode >= 8.2` - Tạo QR code
+
+## 📝 Cấu trúc dự án
+
+```
+vnqr/
+├── src/
+│   └── vnqr/
+│       ├── __init__.py
+│       ├── constants.py      # Các hằng số VietQR
+│       ├── crc.py            # Tính toán CRC
+│       ├── element.py        # Class Element
+│       ├── qr.py             # Tạo QR code image
+│       └── vietqr.py         # Tạo chuỗi VietQR
+├── examples/                 # Các ví dụ sử dụng
+├── tests/                    # Unit tests
+├── pyproject.toml
+└── README.md
+```
+
+## 🧪 Testing
+
+Chạy tests:
+
+```bash
+pytest
+```
+
+Với coverage:
+
+```bash
+pytest --cov=vnqr
+```
+
+## 🤝 Đóng góp
+
+Mọi đóng góp đều được chào đón! Vui lòng:
+
+1. Fork dự án
+2. Tạo branch cho feature mới (`git checkout -b feature/AmazingFeature`)
+3. Commit các thay đổi (`git commit -m 'Add some AmazingFeature'`)
+4. Push lên branch (`git push origin feature/AmazingFeature`)
+5. Mở Pull Request
+
+## 📄 License
+
+Dự án này được phân phối dưới giấy phép MIT. Xem file [LICENSE](LICENSE) để biết thêm chi tiết.
+
+## 👤 Author
+
+**Do Quoc Vuong**
+- Email: vuongtlt13@gmail.com
+- GitHub: [@vuongtlt13](https://github.com/vuongtlt13)
+
+## 🔗 Links
+
+- [Homepage](https://github.com/vuongtlt13/vietqr)
+- [Issues](https://github.com/vuongtlt13/vietqr/issues)
+- [License](https://opensource.org/licenses/MIT)
+
+## ⚠️ Lưu ý
+
+- Package này tạo VietQR code theo tiêu chuẩn NAPAS
+- Mã BIN cần phải chính xác để QR code hoạt động đúng
+- Đảm bảo số tiền và thông tin giao dịch là hợp lệ
+- QR code được tạo là QR động (one-time use)
+
+## 🙏 Acknowledgments
+
+- NAPAS - Tiêu chuẩn VietQR
+- Thư viện [qrcode](https://github.com/lincolnloop/python-qrcode) - Tạo QR code
+
+---
+
+Made with ❤️ in Vietnam
+

vnqr-0.1.0/pyproject.toml

@@ -0,0 +1,81 @@
+[project]
+name = "vnqr"
+version = "0.1.0"
+description = "Thư viện Python để tạo mã QR thanh toán VietQR theo tiêu chuẩn NAPAS, hỗ trợ tạo hình ảnh QR code và thêm icon tùy chỉnh"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [
+    { name = "Do Quoc Vuong", email = "vuongtlt13@gmail.com" },
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+keywords = ['vietqr', 'qr-code', 'bank', 'vietnam', 'Viet Nam', 'qr']
+dependencies = [
+    "crcmod>=1.7",
+    "pypng>=0.20220715.0",
+    "qrcode>=8.2",
+    "requests>=2.32.5",
+    "pillow>=10.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/vuongtlt13/vietqr"
+Issues = "https://github.com/vuongtlt13/vietqr/issues"
+License = "https://opensource.org/licenses/MIT"
+
+[build-system]
+requires = ["uv_build >= 0.9.9, <0.10.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "black>=25.11.0",
+    "coverage>=7.12.0",
+    "isort>=7.0.0",
+    "mypy>=1.18.2",
+    "pre-commit>=4.5.0",
+    "pytest>=9.0.1",
+    "pytest-asyncio>=1.3.0",
+]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+addopts = "-vv --strict-config --strict-markers"
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+
+[tool.coverage.run]
+branch = true
+source = ["vnqr"]
+omit = [
+    "src/tests/*",
+    "src/**/__init__.py",
+    "src/examples/*",
+    "src/vnqr/tools/*",
+]
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = true
+fail_under = 0
+exclude_lines = []
+
+[tool.black]
+line-length = 88
+target-version = ['py310']
+
+[tool.isort]
+profile = "black"
+
+[tool.mypy]
+exclude = '^(?!src/vnqr/).*'
+
+python_version = "3.10"
+ignore_missing_imports = true
+disallow_untyped_calls = false
+disable_error_code = ["no-untyped-def"]
+strict = true

vnqr-0.1.0/src/vnqr/__init__.py

@@ -0,0 +1,11 @@
+from .vietqr import generate_vietqr_string
+from .qr import generate_qr_image, generate_qr_image_with_icon
+from .tools import crawl_bank_info, fetch_banks
+
+__all__ = [
+    "generate_vietqr_string",
+    "generate_qr_image",
+    "generate_qr_image_with_icon",
+    "crawl_bank_info",
+    "fetch_banks",
+]

vnqr-0.1.0/src/vnqr/constants.py

@@ -0,0 +1,60 @@
+from typing import List
+
+
+class VietQRField:
+    # Phiên bản dữ liệu
+    PAYLOAD_FORMAT_INDICATOR = "00"
+
+    # Phương thức khởi tạo
+    INITIATION_METHOD = "01"
+
+    # Thông tin định danh ĐVCNTT
+    MERCHANT_ACCOUNT_INFO = "38"
+
+    # Mã danh mục ĐVCNTT
+    MERCHANT_CATEGORY_CODE = "52"
+
+    # Mã tiền tệ
+    TRANSACTION_CURRENCY = "53"
+
+    # Số tiền GD
+    TRANSACTION_AMOUNT = "54"
+
+    # Chỉ thị cho Tip và Phí GD
+    CONVENIENCE_INDICATOR = "55"
+
+    # Mã quốc gia
+    COUNTRY_CODE = "58"
+
+    # Thông tin bổ sung
+    ADDITIONAL_DATA = "62"
+
+    CRC = "63"
+
+    @classmethod
+    def all(cls) -> List[str]:
+        return [
+            getattr(cls, attr)
+            for attr in dir(cls)
+            if not callable(getattr(cls, attr)) and not attr.startswith("__")
+        ]
+
+
+# ID = 38
+class VietQRMerchantInfoField:
+    # Định danh duy nhất toàn cầu - GUID
+    GUID = "00"
+
+    # Tổ chức thụ hưởng(NHTV,TGTT)
+    ORG_INFO = "01"
+
+    # Mã dịch vụ
+    SERVICE_CODE = "02"
+
+    @classmethod
+    def all(cls) -> List[str]:
+        return [
+            getattr(cls, attr)
+            for attr in dir(cls)
+            if not callable(getattr(cls, attr)) and not attr.startswith("__")
+        ]

vnqr-0.1.0/src/vnqr/crc.py

@@ -0,0 +1,14 @@
+import crcmod
+
+_crc_func = crcmod.mkCrcFun(0x11021, initCrc=0xFFFF, xorOut=0x0000, rev=False)
+
+
+def get_final_crc_hex_string(hex_str: str):
+    return hex_str.upper()[2:].zfill(4)
+
+
+def crc_func(data: str | bytes) -> str:
+    if isinstance(data, str):
+        return get_final_crc_hex_string(hex(_crc_func(data.encode())).upper())
+
+    return get_final_crc_hex_string(hex(_crc_func(data)).upper())

vnqr-0.1.0/src/vnqr/element.py

@@ -0,0 +1,60 @@
+from typing import Tuple
+
+
+class Element:
+    def __init__(self, element_id: str, value: int | str):
+        assert value is not None, "value must be int or str"
+        if isinstance(value, str):
+            assert len(value) > 0, "length of value must be greater than zero"
+        self.element_id = element_id
+        assert len(element_id) <= 2, "length of element id must be less than 2"
+        self.value = value
+
+    @property
+    def value_length(self) -> int:
+        return len(str(self.value))
+
+    def __str__(self):
+        return f"{self.element_id}{self.value_length:02}{self.value}"
+
+    @classmethod
+    def parse(cls, text: str, strict=True) -> Tuple[str, str | int]:
+        element_id, value = cls.try_extract(
+            element_id=text[:2], text=text, strict=strict
+        )
+        if element_id is not None and value is not None:
+            return element_id, value
+        raise ValueError(f"Invalid format! Can't parse `{text}`")
+
+    @classmethod
+    def from_text(cls, text: str, strict=True) -> "Element":
+        element_id, value = cls.parse(text, strict=strict)
+        return cls(element_id=element_id, value=value)
+
+    @classmethod
+    def try_extract(
+        cls, element_id: str, text: str, strict=True
+    ) -> Tuple[str, str | int | None]:
+        try:
+            assert element_id.isdigit(), "element_id must be digits"
+            length = int(text[2:4])
+            value = text[4:]
+            if strict:
+                assert length == len(value), "length not match value length!"
+
+            return element_id, value[:length]
+        except:
+            return element_id, None
+
+    def __eq__(self, other: "Element"):
+        return (
+            isinstance(self, other.__class__)
+            and (self.element_id == other.element_id)
+            and (str(self.value) == str(other.value))
+        )
+
+    def tuple(self):
+        return (
+            self.element_id,
+            self.value,
+        )

vnqr-0.1.0/src/vnqr/qr.py

@@ -0,0 +1,147 @@
+import base64
+import io
+from pathlib import Path
+from typing import BinaryIO
+
+import qrcode
+from qrcode import ERROR_CORRECT_H, ERROR_CORRECT_L
+from qrcode.image.pure import PyPNGImage
+
+try:
+    from PIL import Image
+except ImportError:
+    Image = None  # type: ignore
+
+
+def generate_qr_image(
+    qr_string: str,
+    box_size: int = 5,
+    border: int = 2,
+) -> str:
+    """
+    Tạo QR code image từ chuỗi
+
+    Args:
+        qr_string: Chuỗi để tạo QR code
+        box_size: Kích thước mỗi ô vuông (pixel). Mặc định: 5
+        border: Kích thước viền xung quanh (số ô). Mặc định: 2
+
+    Returns:
+        str: QR code image dạng base64
+
+    Note:
+        Kích thước QR code = (số ô × box_size) + (border × 2 × box_size)
+        Ví dụ: QR 25x25 ô với box_size=5, border=2
+        => (25 × 5) + (2 × 2 × 5) = 125 + 20 = 145 pixels
+    """
+    img = qrcode.make(
+        qr_string,
+        image_factory=PyPNGImage,
+        error_correction=ERROR_CORRECT_L,
+        box_size=box_size,
+        border=border,
+    )
+
+    f = io.BytesIO()
+
+    img.save(f)
+
+    f.seek(0)
+
+    image_content = f.read()
+
+    base64_utf8_str = base64.b64encode(image_content).decode("utf-8")
+
+    return base64_utf8_str
+
+
+def generate_qr_image_with_icon(
+    qr_string: str,
+    icon_path: str | Path | BinaryIO,
+    icon_size_ratio: float = 0.25,
+    error_correction: int = ERROR_CORRECT_H,
+) -> str:
+    """
+    Tạo QR code image với icon ở giữa
+
+    Args:
+        qr_string: Chuỗi để tạo QR code
+        icon_path: Đường dẫn đến file icon (PNG, JPG, v.v.) hoặc file-like object
+        icon_size_ratio: Tỷ lệ kích thước icon so với QR code (0.1 - 0.3 khuyến nghị)
+        error_correction: Mức độ sửa lỗi (ERROR_CORRECT_L, M, Q, H). Mặc định H (cao nhất)
+
+    Returns:
+        str: QR code image dạng base64
+
+    Raises:
+        ImportError: Nếu Pillow chưa được cài đặt
+        ValueError: Nếu icon_path không hợp lệ
+    """
+    if Image is None:
+        raise ImportError(
+            "Pillow (PIL) is required for generating QR code with icon. "
+            "Please install it: pip install Pillow"
+        )
+
+    # Tạo QR code với error correction cao hơn để vẫn scan được khi có icon
+    qr = qrcode.QRCode(
+        version=1,
+        error_correction=error_correction,
+        box_size=10,
+        border=4,
+    )
+    qr.add_data(qr_string)
+    qr.make(fit=True)
+
+    # Tạo QR code image
+    qr_img = qr.make_image(fill_color="black", back_color="white").convert("RGB")
+
+    # Mở và resize icon
+    if isinstance(icon_path, (str, Path)):
+        icon = Image.open(icon_path)
+    else:
+        # File-like object
+        icon = Image.open(icon_path)
+
+    # Convert icon sang RGBA nếu cần (để hỗ trợ transparency)
+    if icon.mode != "RGBA":
+        icon = icon.convert("RGBA")
+
+    # Tính toán kích thước icon
+    qr_width, qr_height = qr_img.size
+    icon_size = (
+        int(qr_width * icon_size_ratio),
+        int(qr_height * icon_size_ratio),
+    )
+
+    # Resize icon (giữ tỷ lệ)
+    # Sử dụng LANCZOS resampling (có thể là Image.Resampling.LANCZOS hoặc Image.LANCZOS)
+    try:
+        resampling = Image.Resampling.LANCZOS  # Pillow >= 10.0.0
+    except AttributeError:
+        resampling = Image.LANCZOS  # Pillow < 10.0.0
+    icon.thumbnail(icon_size, resampling)
+
+    # Tạo một image mới với background trong suốt có cùng kích thước
+    icon_with_bg = Image.new("RGBA", icon_size, (255, 255, 255, 0))
+    
+    # Paste icon vào giữa background
+    icon_x = (icon_size[0] - icon.size[0]) // 2
+    icon_y = (icon_size[1] - icon.size[1]) // 2
+    icon_with_bg.paste(icon, (icon_x, icon_y), icon)
+
+    # Tính toán vị trí để paste icon vào giữa QR code
+    qr_x = (qr_width - icon_size[0]) // 2
+    qr_y = (qr_height - icon_size[1]) // 2
+
+    # Paste icon vào QR code
+    qr_img.paste(icon_with_bg, (qr_x, qr_y), icon_with_bg)
+
+    # Convert về BytesIO và encode base64
+    f = io.BytesIO()
+    qr_img.save(f, format="PNG")
+    f.seek(0)
+    image_content = f.read()
+    base64_utf8_str = base64.b64encode(image_content).decode("utf-8")
+
+    return base64_utf8_str

vnqr-0.1.0/src/vnqr/tools/__init__.py

@@ -0,0 +1,5 @@
+from .craw_bank import crawl_bank_info, fetch_banks
+__all__ = [
+    "crawl_bank_info",
+    "fetch_banks"
+]

vnqr-0.1.0/src/vnqr/tools/craw_bank.py

@@ -0,0 +1,112 @@
+"""
+Crawl thông tin ngân hàng từ API VietQR
+Lấy danh sách ngân hàng và lưu vào file banks.json
+
+Cách sử dụng:
+    pip install requests
+    python src/vnqr/tools/craw_bank.py
+
+Hoặc:
+    python -m vnqr.tools.craw_bank
+
+API: https://api.vietqr.io/v2/banks
+"""
+
+import json
+from pathlib import Path
+from typing import Any
+
+try:
+    import requests
+except Exception:
+    print("Module requests not installed!")
+    raise
+
+
+def fetch_banks() -> dict[str, Any]:
+    """
+    Gọi API để lấy danh sách ngân hàng từ VietQR API
+
+    Returns:
+        dict: Dữ liệu JSON từ API
+
+    Raises:
+        requests.RequestException: Nếu có lỗi khi gọi API
+    """
+    url = "https://api.vietqr.io/v2/banks"
+    
+    print(f"🔄 Đang gọi API: {url}")
+    
+    try:
+        response = requests.get(url, timeout=10)
+        response.raise_for_status()  # Raise exception nếu status code không phải 2xx
+        
+        data = response.json()
+        
+        if data.get("code") == "00":
+            print(f"✅ Lấy dữ liệu thành công! Tổng cộng {len(data.get('data', []))} ngân hàng")
+        else:
+            print(f"⚠️  API trả về code: {data.get('code')}, desc: {data.get('desc')}")
+        
+        return data
+        
+    except requests.Timeout:
+        raise requests.RequestException("⏱️  Timeout khi gọi API. Vui lòng thử lại.")
+    except requests.RequestException as e:
+        raise requests.RequestException(f"❌ Lỗi khi gọi API: {str(e)}")
+
+
+def save_banks_to_file(data: dict[str, Any], output_file: str) -> None:
+    """
+    Lưu dữ liệu ngân hàng vào file JSON
+
+    Args:
+        data: Dữ liệu từ API
+        output_file: Tên file output (mặc định: banks.json)
+    """
+    output_path = Path(output_file)
+    
+    print(f"💾 Đang lưu dữ liệu vào file: {output_path.absolute()}")
+    
+    try:
+        with open(output_path, "w", encoding="utf-8") as f:
+            json.dump(data, f, ensure_ascii=False, indent=2)
+        
+        print(f"✅ Đã lưu thành công vào {output_path.absolute()}")
+        
+        # In thống kê
+        banks = data.get("data", [])
+        if banks:
+            print(f"\n📊 Thống kê:")
+            print(f"  - Tổng số ngân hàng: {len(banks)}")
+            
+            # Đếm số ngân hàng hỗ trợ transfer
+            transfer_supported = sum(1 for bank in banks if bank.get("transferSupported") == 1)
+            print(f"  - Ngân hàng hỗ trợ chuyển khoản: {transfer_supported}")
+            
+            # In một vài ngân hàng đầu tiên
+            print(f"\n📋 Một số ngân hàng:")
+            for bank in banks[:5]:
+                print(f"  - {bank.get('shortName')} ({bank.get('code')}): BIN {bank.get('bin')}")
+            
+            if len(banks) > 5:
+                print(f"  ... và {len(banks) - 5} ngân hàng khác")
+    
+    except IOError as e:
+        raise IOError(f"❌ Lỗi khi ghi file: {str(e)}")
+
+
+def crawl_bank_info(output_file: str="banks.json") -> None:
+    """Hàm main để chạy script"""
+    try:
+        # Gọi API lấy dữ liệu
+        data = fetch_banks()
+        
+        # Lưu vào file
+        save_banks_to_file(data, output_file=output_file)
+        
+        print("\n🎉 Hoàn thành!")
+        
+    except Exception as e:
+        print(f"\n❌ Có lỗi xảy ra: {str(e)}")
+        raise

vnqr-0.1.0/src/vnqr/vietqr.py

@@ -0,0 +1,93 @@
+from .qr import generate_qr_image
+from .constants import VietQRField, VietQRMerchantInfoField
+from .crc import crc_func
+from .element import Element
+
+
+def generate_vietqr_string(
+    bank_bin: str,
+    bank_account: str,
+    total_amount: int,
+    content: str,
+) -> str:
+    # Phiên bản dữ liệu (ID 00)
+    # Phiên bản dữ liệu có giá trị là “01”.
+    version_element = Element(
+        element_id=VietQRField.PAYLOAD_FORMAT_INDICATOR, value="01"
+    )
+
+    # Phương thức khởi tạo (ID 01)
+    # - “11” = QR tĩnh – áp dụng khi mã QR cho phép thực hiện nhiều lần giao dịch.
+    # - “12” = QR động – áp dụng khi mã QR chỉ cho phép thực hiện một lần giao dịch.
+    init_method = Element(element_id=VietQRField.INITIATION_METHOD, value="12")
+
+    # Thông tin định danh ĐVCNTT (ID 38)
+    # ID 38 được sử dụng cho dịch vụ VietQR qua hệ thống Napas.
+
+    # ID quy định dữ liệu với 1 trong các giá trị sau:
+    # AID: luôn có giá trị “A000000727”.
+    merchant_info_guid = Element(
+        element_id=VietQRMerchantInfoField.GUID, value="A000000727"
+    )
+
+    # merchant_info_org_info
+    merchant_info_org_info_acquirer = Element(element_id="00", value=bank_bin)
+    merchant_info_org_info_consumer = Element(element_id="01", value=bank_account)
+    merchant_info_org_info = Element(
+        element_id=VietQRMerchantInfoField.ORG_INFO,
+        value=f"{merchant_info_org_info_acquirer}{merchant_info_org_info_consumer}",
+    )
+
+    # merchant_info_service_code
+    # - QRIBFTTC: dịch vụ chuyển nhanh NAPAS247 bằng mã QR đến thẻ
+    # - QRIBFTTA: dịch vụ chuyển nhanh NAPAS247 bằng mã QR đến Tài khoản
+    merchant_info_service_code = Element(
+        element_id=VietQRMerchantInfoField.SERVICE_CODE,
+        value="QRIBFTTA",
+    )
+
+    merchant_info = Element(
+        element_id=VietQRField.MERCHANT_ACCOUNT_INFO,
+        value=f"{merchant_info_guid}{merchant_info_org_info}{merchant_info_service_code}",
+    )
+
+    # Mã tiền tệ (ID 53)
+    currency_code = Element(element_id=VietQRField.TRANSACTION_CURRENCY, value="704")
+
+    # Số tiền giao dịch (ID 54)
+    transaction_amount = Element(
+        element_id=VietQRField.TRANSACTION_AMOUNT, value=f"{total_amount}"
+    )
+
+    # Mã quốc gia (ID 58)
+    country_code = Element(element_id=VietQRField.COUNTRY_CODE, value="VN")
+
+    # Thông tin bổ sung (ID 62)
+    # Mục đích giao dịch (08)
+    additional_info_purpose = Element(element_id="08", value=f"{content}")
+    additional_info = Element(
+        element_id=VietQRField.ADDITIONAL_DATA, value=f"{additional_info_purpose}"
+    )
+
+    # Mã kiểm thử giá trị - CRC (ID 63)
+    before_crc_data = f"{version_element}{init_method}{merchant_info}{currency_code}{transaction_amount}{country_code}{additional_info}{VietQRField.CRC}04"
+    crc_element = Element(element_id=VietQRField.CRC, value=crc_func(before_crc_data))
+    return f"{version_element}{init_method}{merchant_info}{currency_code}{transaction_amount}{country_code}{additional_info}{crc_element}"
+
+
+def generate_vietqr_image(
+    bank_bin: str,
+    bank_account: str,
+    total_amount: int,
+    content: str,
+) -> str:
+    vietqr_string = generate_vietqr_string(
+        bank_bin=bank_bin,
+        bank_account=bank_account,
+        total_amount=total_amount,
+        content=content,
+    )
+
+    return generate_qr_image(
+        qr_string=vietqr_string,
+    )