From ceda6efd64ec63cb5e8ae6367d68ec474e11adce Mon Sep 17 00:00:00 2001
From: ndthanhdev <ndthanhdev@outlook.com>
Date: Fri, 3 Jul 2026 11:25:53 +0000
Subject: [PATCH] chore: add qr skill

---
 skills/vietqr-quick-link/SKILL.md             |  40 +++++++
 .../references/bank-list-api.md               |  79 ++++++++++++++
 .../references/quick-link.md                  | 103 ++++++++++++++++++
 .../references/tax-code-api.md                |  48 ++++++++
 4 files changed, 270 insertions(+)
 create mode 100644 skills/vietqr-quick-link/SKILL.md
 create mode 100644 skills/vietqr-quick-link/references/bank-list-api.md
 create mode 100644 skills/vietqr-quick-link/references/quick-link.md
 create mode 100644 skills/vietqr-quick-link/references/tax-code-api.md

diff --git a/skills/vietqr-quick-link/SKILL.md b/skills/vietqr-quick-link/SKILL.md
new file mode 100644
index 0000000..81156e0
--- /dev/null
+++ b/skills/vietqr-quick-link/SKILL.md
@@ -0,0 +1,40 @@
+---
+name: vietqr-quick-link
+description: >
+  VietQR payment QR code integration. Use this skill when working with VietQR
+  Quick Links, QR code image generation, or any VietQR-related payment feature
+  in Vietnam.
+---
+
+# VietQR Integration Guide
+
+VietQR is the national QR payment standard in Vietnam, established by **NAPAS**
+(National Payment Corporation of Vietnam) on June 15, 2021. **VietQR.io** (by
+Casso Company) provides a developer-friendly Payment Kit to implement VietQR
+via Quick Links.
+
+Over **40+ banking apps** in Vietnam support scanning VietQR codes.
+
+## Reference Documentation
+
+| Reference                                                 | Contents                                                       |
+| --------------------------------------------------------- | -------------------------------------------------------------- |
+| [quick-link.md](references/quick-link.md)                 | Quick Link syntax, parameters, templates, and image generation |
+| [bank-list-api.md](references/bank-list-api.md)           | Public API to look up bank BIN codes, short names, NAPAS codes |
+| [tax-code-api.md](references/tax-code-api.md)             | Public API to look up business info by tax code                |
+
+## Quick Start
+
+Generate a VietQR image via URL — **no API key needed**:
+
+```
+https://img.vietqr.io/image/<BANK_ID>-<ACCOUNT_NO>-<TEMPLATE>.png?amount=<AMOUNT>&addInfo=<DESCRIPTION>&accountName=<ACCOUNT_NAME>
+```
+
+Example:
+
+```
+https://img.vietqr.io/image/vietinbank-113366668888-compact2.jpg?amount=790000&addInfo=dong%20qop%20quy%20vac%20xin&accountName=Quy%20Vac%20Xin%20Covid
+```
+
+See [references/quick-link.md](references/quick-link.md) for full parameter details.
diff --git a/skills/vietqr-quick-link/references/bank-list-api.md b/skills/vietqr-quick-link/references/bank-list-api.md
new file mode 100644
index 0000000..f2031f4
--- /dev/null
+++ b/skills/vietqr-quick-link/references/bank-list-api.md
@@ -0,0 +1,79 @@
+# VietQR Bank List API
+
+Returns the list of banks supported by VietQR. Use this to look up bank BIN
+codes, short names, and NAPAS codes needed for Quick Links.
+
+## Endpoint
+
+```
+GET https://api.vietqr.io/v2/banks
+```
+
+> **No authentication required.**
+
+## Response
+
+### Success Response (HTTP 200)
+
+```json
+{
+  "code": "00",
+  "desc": "Get Bank list successful! Total 55 banks",
+  "data": [
+    {
+      "id": 1,
+      "name": "Ngân hàng TMCP An Bình",
+      "code": "ABB",
+      "bin": "970425",
+      "shortName": "ABBANK",
+      "logo": "https://api.vietqr.io/img/ABB.png",
+      "transferSupported": 1,
+      "lookupSupported": 1
+    },
+    {
+      "id": 2,
+      "name": "Ngân hàng TMCP Á Châu",
+      "code": "ACB",
+      "bin": "970416",
+      "shortName": "ACB",
+      "logo": "https://api.vietqr.io/img/ACB.png",
+      "transferSupported": 1,
+      "lookupSupported": 1
+    }
+  ]
+}
+```
+
+### Response Fields
+
+| Field                | Type    | Description                                                         |
+| -------------------- | ------- | ------------------------------------------------------------------- |
+| `id`                 | integer | Internal bank identifier                                            |
+| `name`               | string  | Full official bank name (in Vietnamese)                             |
+| `code`               | string  | NAPAS-assigned bank abbreviation (e.g., `ACB`, `ICB`, `VCB`)       |
+| `bin`                | string  | 6-digit bank BIN code assigned by the State Bank of Vietnam         |
+| `shortName`          | string  | Common short name / popular abbreviation                            |
+| `logo`               | string  | URL to the bank's logo image                                        |
+| `transferSupported`  | integer | `1` if the bank supports VietQR transfers, `0` otherwise           |
+| `lookupSupported`    | integer | `1` if the bank supports account name lookup, `0` otherwise        |
+
+## Usage in Quick Link
+
+Any of these fields can be used as `<BANK_ID>` in a Quick Link URL:
+
+- **`bin`** (e.g., `970415`) — the BIN code
+- **`shortName`** (e.g., `Vietinbank`) — the common name
+- **`code`** (e.g., `ICB`) — the NAPAS code
+
+```
+https://img.vietqr.io/image/970415-113366668888-compact.png
+https://img.vietqr.io/image/vietinbank-113366668888-compact.png
+https://img.vietqr.io/image/ICB-113366668888-compact.png
+```
+
+All three URLs above generate the same QR code.
+
+## Caching Advice
+
+The bank list may change over time (banks added, removed, or updated).
+If you cache the response, **refresh it daily** to stay up to date.
diff --git a/skills/vietqr-quick-link/references/quick-link.md b/skills/vietqr-quick-link/references/quick-link.md
new file mode 100644
index 0000000..04e11a5
--- /dev/null
+++ b/skills/vietqr-quick-link/references/quick-link.md
@@ -0,0 +1,103 @@
+# VietQR Quick Link
+
+Quick Link is the simplest way to generate a VietQR payment QR code image — no
+API key required. It returns an image (PNG/JPG) that can be embedded directly
+in `<img>` tags, emails, documents, etc.
+
+## Full Syntax
+
+```
+https://img.vietqr.io/image/<BANK_ID>-<ACCOUNT_NO>-<TEMPLATE>.<FORMAT>?amount=<AMOUNT>&addInfo=<DESCRIPTION>&accountName=<ACCOUNT_NAME>
+```
+
+> Use a hyphen (`-`) as the separator between parameters.
+
+### Example
+
+```
+https://img.vietqr.io/image/vietinbank-113366668888-compact2.jpg?amount=790000&addInfo=dong%20qop%20quy%20vac%20xin&accountName=Quy%20Vac%20Xin%20Covid
+```
+
+---
+
+## Parameter Reference
+
+### 1. `<BANK_ID>` (required)
+
+The bank identifier. Accepts any of the following formats:
+
+| Format              | Example      | Description                                      |
+| ------------------- | ------------ | ------------------------------------------------ |
+| BIN code            | `970415`     | 6-digit bank BIN assigned by the State Bank       |
+| Common short name   | `vietinbank` | Popular abbreviated name                          |
+| NAPAS code          | `ICB`        | Official NAPAS-assigned abbreviation              |
+
+> Look up BIN (`bin`), short name (`shortName`), and code (`code`) via the
+> [Bank List API](bank-list-api.md).
+
+### 2. `<ACCOUNT_NO>` (required)
+
+The beneficiary's bank account number.
+
+- Alphanumeric characters only (letters or digits)
+- Maximum **19 characters**
+- Also supports **Alias Names** and **Virtual Account Numbers**
+
+### 3. `<TEMPLATE>` (required)
+
+Determines the visual layout of the generated QR image.
+
+| Template     | Size (px)   | Description                                                       |
+| ------------ | ----------- | ----------------------------------------------------------------- |
+| `compact2`   | 540 × 640   | QR code + logos + transfer details                                |
+| `compact`    | 540 × 540   | QR code + VietQR, NAPAS, and bank logos                           |
+| `qr_only`    | 480 × 480   | Plain QR code only                                                |
+| `print`      | 600 × 776   | QR code + logos + full transfer details (print-friendly)          |
+| `loax2`      | 583 × 3719  | QR code + logos + transfer info, for payment speaker products     |
+
+> For production use, create a **custom template** at
+> [my.vietqr.io](https://my.vietqr.io) inheriting from one of the base themes
+> above, then use its template ID in the Quick Link.
+
+### 4. `<AMOUNT>` (optional, query parameter)
+
+The transfer amount.
+
+- Must be a **positive integer**
+- Maximum **13 digits**
+
+### 5. `<DESCRIPTION>` (optional, query parameter `addInfo`)
+
+The transfer description / memo.
+
+- Maximum **50 characters**
+- No special characters allowed
+
+### 6. `<ACCOUNT_NAME>` (optional, query parameter)
+
+The beneficiary name displayed on the QR image.
+
+> This field is for **display purposes only** and is not part of the VietQR
+> standard QR data payload.
+
+---
+
+## Image Format
+
+The file extension in the URL determines the output format:
+
+| Extension | Format |
+| --------- | ------ |
+| `.png`    | PNG    |
+| `.jpg`    | JPEG   |
+
+---
+
+## Custom Templates
+
+To use Quick Link in production projects, create your own branded template:
+
+1. Go to [my.vietqr.io](https://my.vietqr.io) and register a new account
+2. Create a new template
+3. Choose a base theme, update logo, and customize colors to match your brand
+4. Replace `<TEMPLATE>` in the Quick Link URL with your new template's ID
diff --git a/skills/vietqr-quick-link/references/tax-code-api.md b/skills/vietqr-quick-link/references/tax-code-api.md
new file mode 100644
index 0000000..ecbe7dd
--- /dev/null
+++ b/skills/vietqr-quick-link/references/tax-code-api.md
@@ -0,0 +1,48 @@
+# VietQR Tax Code Lookup API
+
+Look up business information by Vietnamese tax code (Mã số thuế). Useful for
+retrieving invoice details when a customer makes a payment.
+
+## Endpoint
+
+```
+GET https://api.vietqr.io/v2/business/{taxCode}
+```
+
+> **No authentication required.**
+
+### Path Parameters
+
+| Parameter  | Required | Type   | Description                |
+| ---------- | -------- | ------ | -------------------------- |
+| `taxCode`  | Yes      | string | Business tax code          |
+
+## Response
+
+### Success Response (HTTP 200)
+
+```json
+{
+  "code": "00",
+  "desc": "Success",
+  "data": {
+    "id": "0316794479",
+    "name": "CÔNG TY TNHH CASSO",
+    "internationalName": "CASSO COMPANY LIMITED",
+    "shortName": "CASSO",
+    "address": "I.102D, Nhà A, Khu Công Nghệ Phần Mềm, ..."
+  }
+}
+```
+
+### Response Fields
+
+| Field               | Type   | Description                                      |
+| ------------------- | ------ | ------------------------------------------------ |
+| `code`              | string | Response code. `"00"` = success                  |
+| `desc`              | string | Human-readable result description                |
+| `data.id`           | string | Tax code                                         |
+| `data.name`         | string | Official business name (Vietnamese)              |
+| `data.internationalName` | string | International / English business name       |
+| `data.shortName`    | string | Abbreviated business name                        |
+| `data.address`      | string | Registered business address                      |