JSON ↔ Excel: BOM UTF-8, sheet và lỗi tiếng Việt khi mở CSV【2026】

PM gửi message: “Cho em file Excel đơn hàng từ API này được không?” Bạn copy response JSON vào Notepad, Save as .csv, double-click. Cột Khách hàng thành Khách hà ng. Mentor nhìn một cái: “BOM và encoding — classic.”

Bài này nhìn góc Excel: không giảng lại “JSON là gì”, mà tập trung đưa dữ liệu API vào spreadsheet (và chiều ngược) mà không mất tiếng Việt, không vỡ cột, không ảo tưởng về “nhiều sheet trong CSV”.

Bài viết này giúp bạn

• Hiểu vì sao Excel Windows hay phá UTF-8 và BOM giải quyết gì
• Map nested JSON → cột phẳng trước khi mở sheet
• Tránh nhầm CSV ≠ workbook nhiều sheet
• Checklist trước khi gửi file cho non-tech
• Dùng công cụ JSON↔CSV chạy local như bước trung gian

---

Excel cần gì — JSON có gì?

	JSON (API)	Excel / CSV
Cấu trúc	Cây, nested, mảng trong object	Lưới hàng × cột (một sheet = một bảng)
Kiểu dữ liệu	number, boolean, null, object	Chủ yếu text/number sau khi mở; kiểu dễ bị Excel “đoán”
Tiếng Việt	UTF-8 trong HTTP gần như mặc định	File CSV trên Windows dễ đoán nhầm encoding
Nhiều bảng	Một payload nhiều key	Nhiều sheet trong .xlsx — CSV chỉ một bảng

Quy tắc thực dụng: mỗi lần “cho Excel” = chọn một mảng record, flatten thành cột, xuất một CSV (hoặc một sheet). Cần quan hệ 1-n (order + line items) → hai sheet / hai file, đừng nhét mảng vào một ô rồi kỳ vọng filter đẹp.

---

BOM UTF-8: lý do tên tiếng Việt bị vỡ

BOM (Byte Order Mark) với UTF-8 là ba byte EF BB BF ở đầu file. Không bắt buộc theo chuẩn Unicode cho UTF-8, nhưng Excel trên Windows thường dùng BOM như tín hiệu “đây là UTF-8”.

Không có BOM:

Nguyễn Văn A  →  hiển thị kiểu Nguyá»…n / Khách hà ng

Có BOM: Excel nhận đúng dấu tiếng Việt trong hầu hết bản Office phổ biến.

Cách xử lý thực tế

1. Google Sheets: File → Import → Upload CSV (UTF-8) — thường ổn hơn double-click trên Windows.
2. Excel: Data → Get Data → From Text/CSV → chọn File Origin = UTF-8, không double-click nếu đã từng lỗi.
3. Lưu file từ editor: chọn “UTF-8 with BOM” / “UTF-8-SIG” (Python).
4. Sau khi dùng tool trình duyệt: kết quả CSV là text thuần. Khi Save As để gửi khách Windows, thêm BOM nếu họ hay mở bằng double-click.

Ví dụ thêm BOM khi đã có chuỗi CSV trong tay (Node):

import fs from "node:fs";
const csv = "name,city\nNguyễn,Hà Nội\n";
fs.writeFileSync("orders.csv", "\uFEFF" + csv, "utf8");

Công cụ chuyển đổi trên web không nhất thiết tự gắn BOM — đó là bước lưu file cho Excel, không phải bước parse JSON. Đừng kỳ vọng mọi converter online đều “Excel-ready” nếu bạn chỉ copy từ textarea.

---

Nested JSON → cột sheet: flatten có chủ đích

API điển hình:

[
  {
    "id": 101,
    "customer": { "name": "Nguyễn An", "city": "Đà Nẵng" },
    "total": 1500000,
    "tags": ["vip", "retail"]
  }
]

JSON → CSV trên Kawa flatten object lồng thành header dạng customer.name, customer.city. Mảng tags không phải object thuần — thường thành chuỗi JSON trong một ô hoặc cần quyết định riêng (join bằng ;, hoặc tách bảng).

Trước khi đưa cho kế toán / CSKH, hãy trả lời:

• Cột nào bắt buộc trên sheet?
• Field nested nào được phép bỏ?
• Mảng con: một ô hay sheet thứ hai?

---

Sheet Excel ≠ “nhiều bảng trong một CSV”

CSV là một bảng: dòng 1 = header, các dòng sau = record. Không có tab sheet, không có formula, không có merge cell.

Nhu cầu	Định dạng nên dùng
Gửi PM lọc nhanh 1 bảng	CSV (UTF-8 ± BOM) hoặc Sheets
Nhiều bảng liên quan + format	.xlsx (Excel / SheetJS)
Đưa lại cho API	JSON mảng object
Doc README	Markdown table (không thay CSV phân tích)

Nếu khách đòi “file Excel có 3 sheet”, đừng export một CSV rồi đổi đuôi thành .xlsx — Excel có thể mở nhưng không tạo sheet thật. Hãy export 3 CSV hoặc dùng thư viện ghi xlsx.

---

Chiều ngược: Excel / CSV → JSON cho dev

1. Trong Excel: lưu CSV UTF-8 (hoặc copy vùng → paste; clipboard thường tab-separated — khác CSV).
2. Dán vào chế độ CSV → JSON trên công cụ.
3. Kiểm tra: mọi giá trị thường thành string ("1500000", "true"). Parse số / boolean lại trong code nếu API cần đúng kiểu.
4. Header trùng hoặc trống → object key xấu; sửa header trên sheet trước khi convert.

Locale delimiter: một số máy Excel châu Âu xuất ; thay vì ,. Tool Kawa parse theo dấu phẩy. Nếu file dùng ;, đổi delimiter hoặc mở Sheets rồi export lại CSV chuẩn comma.

---

Case study 1: Outsource nhận JSON đơn hàng, khách dùng Excel 365 tiếng Việt

Triệu chứng: Cột địa chỉ có dấu phẩy "12 Nguyễn Huệ, Q.1" làm Excel tách thành nhiều cột.

Nguyên nhân: CSV không được quote đúng khi tự viết script rows.join(",").

Cách xử lý: Dùng converter có escapeCsv (quote khi có , " hoặc xuống dòng). Sau đó mở Excel bằng From Text/CSV, xác nhận số cột = số header.

---

Case study 2: Freelancer đưa sample API cho BA — PII

Payload có SĐT và email thật. Upload “JSON to Excel online” lạ = rủi ro hợp đồng.

Quy trình an toàn:

1. Che PII trên bản copy (sđt → 090****123)
2. Chuyển bằng JSON ↔ CSV local
3. Thêm BOM nếu khách double-click trên Windows
4. Gửi file; giữ bản JSON gốc trong repo private

---

Quy trình 8 phút: API → sheet đẹp

1. Network tab → Copy response → chỉ lấy mảng record (data / items / results)
2. Mở /vi/tools/json-csv/ → JSON → CSV
3. Đếm cột header; đổi tên cột dài (customer.name → Tên KH) trên Excel sau nếu cần
4. Save với UTF-8 BOM khi khách dùng Excel Windows
5. Smoke-test 3 dòng có tiếng Việt + 1 dòng có dấu phẩy trong địa chỉ
6. Mới gửi file / đưa vào pivot

---

Checklist trước khi bảo “đã xuất Excel”

• Input là mảng object, không phải object bọc chưa mở
• Nested đã flatten hoặc đã cắt field theo nhu cầu sheet
• Mảng con (line items) đã có chiến lược: ô / sheet 2 / bỏ
• Tiếng Việt: UTF-8 + (BOM hoặc Import UTF-8), không mở nhầm ANSI
• Ô có dấu phẩy / nháy kép đã được quote
• Không giả CSV thành multi-sheet workbook
• Dữ liệu nhạy cảm xử lý trên trình duyệt / máy local

---

Lỗi thường gặp (và cách đọc)

Hiện tượng	Nguyên nhân gần đúng	Việc làm ngay
Nguyá»…n / Khách	UTF-8 đọc như Windows-1252	BOM hoặc Import UTF-8
Một cột bị tách nhiều cột	Dấu phẩy trong giá trị, thiếu quote	Dùng converter chuẩn / kiểm tra escape
Thiếu cột nested	Chưa flatten / chọn nhầm mảng	Kiểm tra user.name trên header
"true" thay vì boolean	CSV→JSON luôn string	Ép kiểu trong app
Tool báo cần mảng JSON	Dán object {} hoặc text không phải JSON	Bọc [{...}] hoặc JSON.parse đúng

---

Liên kết liên quan

• JSON ↔ CSV — chuyển hai chiều, flatten nested, chạy local
• JSON Formatter — sửa lỗi cú pháp trước khi convert
• Markdown Table — khi cần bảng cho README, không phải phân tích Excel
• Danh sách công cụ