vn-skills

Create a VietQR (NAPAS 247) bank-transfer QR payload. Returns the EMVCo string, CRC and optionally a PNG image. Bank accepts BIN (970436), code (VCB) or name (Vietcombank). Amount is integer VND; note is sanitized (no diacritics, max 25 chars).

Decode a VietQR / EMVCo QR payload string: bank, account, amount, note, and whether the CRC is valid.

Read the QR code in a PNG image file and decode it like vietqr_parse: bank, account, amount, note, CRC validity. Returns READ_ERROR for an unreadable/non-PNG file and NO_QR when no QR code is found.

Search the NAPAS bank list by BIN, code, short name, full name or SWIFT/BIC code. Empty query lists all banks.

Parse a free-text Vietnamese address into province / ward / street using the post-01/07/2025 catalogue (34 provinces, no districts). Handles missing diacritics and abbreviations (TP.HCM, Q.1, P. Bến Nghé). Set mode "legacy" for pre-2025 addresses with districts.

Convert up to 1000 pre-July-2025 Vietnamese free-text addresses (63 provinces, districts, wards) into the new 2-level structure (34 provinces, wards) in one call. Returns per-row results plus a summary of converted and failed rows. Null, empty or non-string entries do not fail the call: they come back as failed rows (ok:false with an error code) and are counted in summary.failed.

Convert a pre-July-2025 Vietnamese address (63 provinces, districts, wards) into the new 2-level structure (34 provinces, wards). Returns the new ward/province, mapping type (unchanged/merged/divided) and all candidates when the old ward was split. When the client supports elicitation, the server may ask the user to pick the new ward for a split old ward (chosenBy: user|default).

Find current (post-2025) wards by name, optionally within a province.

Offline validation of a Vietnamese tax ID (mã số thuế): 10 digits (enterprise), 13 digits (branch, e.g. 0100233488-001) with check-digit verification, or 12-digit personal ID (format only). Does not query the tax authority.

Offline validation and decoding of a 12-digit CCCD (province, sex, birth year; legacy province mapped to 2025 province) or format check of a 9-digit CMND. Format validity does not prove the identity exists.

Normalise a Vietnamese phone number (0/84/+84, old 11-digit 01xx mobile prefixes) to national and E.164 forms and classify it: mobile (original carrier) or landline (area code, province). Offline.

Split a Vietnamese full name into họ / tên đệm / tên (handles Tôn Thất, Nguyễn Phúc), plus slug and initials; or sort a list of names by tên with Vietnamese collation.

Read an integer VND amount in Vietnamese words, e.g. 1200000 -> "một triệu hai trăm nghìn đồng". Also reads plain numbers without a unit with plain: true, e.g. 30 -> "ba mươi". Options: thousand "nghìn"/"ngàn", odd "lẻ"/"linh", capitalize, unit.

Rewrite numbers, VND amounts (1.250.000đ, 500k), percentages, phone numbers and dd/mm/yyyy dates in text as spoken Vietnamese for text-to-speech. Decimals and partial dates are left unchanged and listed in skipped. Returns text, changes, skipped.

Parse an amount written in Vietnamese words back to digits, e.g. "một triệu hai trăm nghìn đồng" -> "1200000". Returns value (digit string), negative, unit, chan.

Format numbers/VND/dates the Vietnamese way (1.234.567,89; 1.200.000 ₫; 1,2 triệu; dd/MM/yyyy) or parse typed amounts ("1tr2", "500k", "1,5 tỷ"; "1.500" = 1500).

Convert a Gregorian date (dd/mm/yyyy or yyyy-mm-dd) to the Vietnamese lunar date with can chi (e.g. Ất Tỵ), zodiac, leap-month flag and solar term. Optional hour (0-23) adds hourCanChi, hourBranch, hourRange (giờ sinh).

Convert a Vietnamese lunar date to the Gregorian date. Set leap=true for the leap (nhuận) month.

Turn a Vietnamese date phrase into a solar date: lunar ("rằm tháng Giêng năm sau", "mùng 1 Tết", "23 tháng Chạp"), relative ("ngày mai", "3 ngày nữa", "thứ Sáu tuần sau") or Gregorian. ref (yyyy-mm-dd) defaults to today in UTC+7.

Calendar of a Gregorian month: each day with lunar date (leap flag, mùng 1, rằm), day can chi, solar term starts and holidays/days off.

List Vietnamese holidays for a solar year (Tết, Giỗ Tổ Hùng Vương, 30/4, 1/5, 2/9, Trung thu...). Lunar holidays are resolved to solar dates. publicOnly limits to official days off.

Official days off for public-sector staff in a year (2023-2199): Tết Dương lịch, Tết Âm lịch, Giỗ Tổ Hùng Vương, 30/4, 1/5, Quốc khánh, Ngày Văn hóa Việt Nam 24/11 (from 2026), with nghỉ bù and swapped working Saturdays from the Government notice. Unannounced years return the statutory days, announced: false and the pending Tết / National Day days.

Export the official days off of a year (2023-2199) as iCalendar (RFC 5545) text for Google Calendar, Outlook or Apple Calendar: holidays, nghỉ bù, swapped days and (optionally) working Saturdays. Unannounced years omit pending days and list them in warnings.

Whether a date is a working day for public-sector staff (Monday-Friday minus holidays and nghỉ bù, plus swapped Saturdays). certain: false when the year is not announced and the date may still become a Tết or National Day day off.

The date n working days after (or before, n < 0) a date, skipping weekends, holidays and nghỉ bù; the start date is not counted. certain: false if unannounced days were crossed.

Number of working days in (from, to]: the start date is not counted, the end date is; negative if to is before from. Skips weekends, holidays and nghỉ bù. certain: false if unannounced Tết or National Day days were crossed.

Validate an e-invoice (hóa đơn điện tử) object against the mandatory contents of Decree 123/2020 (series, date, seller tax ID, lines, VAT rates 0/5/8/10/KCT/KKKNT).

Validate an invoice and compute line amounts, VAT per rate, grand total and the total in Vietnamese words.

Apply VAT to a net amount, or with inclusive=true split a VAT-inclusive price (giá đã gồm VAT) into net (tiền hàng) and VAT. Rates 0/5/8/10/KCT/KKKNT. Net is rounded half away from zero and the leftover đồng goes to VAT (library convention).

Issue an invoice through the in-memory MOCK provider (no real API, nothing persisted). Useful for testing integrations before wiring MISA/Viettel/VNPT sandbox adapters.

Solar date of Tết (lunar new year) for a year, with can chi and leap month.

Can chi (e.g. Giáp Thìn) of a lunar year, with its leap month if any.

Compute the 10th check digit of a Vietnamese tax ID from its first 9 digits.

List the 34 current Vietnamese provinces (since 01/07/2025) with ward counts.

Takes no parameters.

List the pre-01/07/2025 wards (with district and province) that became a current ward, by ward code or name.

Look up one current province by name, alias (e.g. "TP.HCM") or 2-digit code.

Return a valid example invoice object to start from.

Takes no parameters.