JSON và API: cách các phần mềm nói chuyện với nhau

Hãy tưởng tượng mỗi chi nhánh Bánh Mộc tự ghi phiếu đặt bánh gửi bếp trung tâm theo kiểu riêng: Phú Nhuận viết tay, Thảo Điền nhắn Zalo, Gò Vấp gọi điện. Anh Tuấn sẽ phải “dịch” ba kiểu khác nhau mỗi sáng. Giải pháp là một mẫu phiếu chung: ô nào ghi gì, viết theo định dạng nào.

JSON (JavaScript Object Notation) chính là mẫu phiếu chung của thế giới phần mềm. Dù tên có chữ JavaScript, JSON được hầu hết ngôn ngữ (Python, PHP, Go, Java…) đọc và viết được. Nó là chữ thuần, con người cũng đọc được.

Cú pháp JSON trong năm phút

JSON chỉ có vài quy tắc:

• Object (phiếu có các ô tên): nằm trong { }, gồm các cặp "tên": giá trị, phân cách bằng dấu phẩy.
• Array (danh sách): nằm trong [ ], các phần tử phân cách bằng dấu phẩy.
• Tên ô (key) luôn là chuỗi trong dấu nháy kép "...".
• Giá trị chỉ có sáu loại:

Bạn sẽ thấy JSON rất giống object và array trong TypeScript ở bài Đọc hiểu code cơ bản01-04. Điều đó không ngẫu nhiên; JSON được phát triển từ cách viết đó, nhưng chặt chẽ hơn.

Một đơn hàng Bánh Mộc dạng JSON

Đây là đơn của chị Hương (đơn quen thuộc từ các bài trước) khi Mộc OMS trả về cho một ứng dụng khác. Tên các ô bám theo mô hình dữ liệu của dự án (orders, order_items, customers), nhưng viết theo quy ước camelCase của API: database lưu delivery_at, API trả deliveryAt; mã định danh (id) là chuỗi uuid:

{
  "code": "BM-261012-007",
  "channel": "zalo",
  "status": "da_xac_nhan",
  "branch": { "id": "b1a7c3e2-5d4f-4a6b-8c9d-0e1f2a3b4c5d", "name": "Bánh Mộc Phú Nhuận" },
  "customer": {
    "id": "c2b8d4f3-6e5a-4b7c-9d0e-1f2a3b4c5d6e",
    "fullName": "Trần Thị Hương",
    "phone": "0901234123"
  },
  "deliveryType": "delivery",
  "deliveryAt": "2026-10-13T15:00:00+07:00",
  "deliveryAddress": "45 đường Số 7, phường Mẫu, TP.HCM",
  "items": [
    {
      "productId": "a3c9e5f4-7f6b-4c8d-8e1f-2a3b4c5d6e7f",
      "productName": "Bánh kem dâu 20cm",
      "isCustomCake": true,
      "quantity": 1,
      "unitPrice": 450000,
      "cakeMessage": "Mừng sinh nhật Bin",
      "options": { "size": "20cm", "flavor": "dâu", "candles": 5 }
    },
    {
      "productId": "d4dae6a5-8a7c-4d9e-9f2a-3b4c5d6e7f80",
      "productName": "Bánh quy hộp quà",
      "isCustomCake": false,
      "quantity": 2,
      "unitPrice": 120000,
      "cakeMessage": null,
      "options": {}
    }
  ],
  "subtotal": 690000,
  "shippingFee": 0,
  "total": 690000,
  "deposit": 345000,
  "paymentStatus": "deposit",
  "note": "Gọi trước khi giao 15 phút",
  "createdAt": "2026-10-12T09:24:00+07:00"
}

(Tên, số điện thoại, địa chỉ là dữ liệu minh họa.)

Đọc từ trên xuống như đọc một phiếu:

• Đơn BM-261012-007, nhận qua Zalo, đã xác nhận, thuộc chi nhánh Phú Nhuận.
• Khách là một object lồng bên trong (customer), có mã, tên, số điện thoại.
• items là một danh sách hai món. Món đầu là bánh kem tùy chỉnh (isCustomCake: true), có chữ trên bánh và các tùy chọn size, vị, số nến. Món thứ hai không có chữ (null) và không có tùy chọn ({}).
• Các con số tiền khớp với phép tính bạn đã “chạy tay” ở bài 01-04: 450.000 + 2 × 120.000 = 690.000, giao tận nơi nhưng từ 500.000 nên miễn ship, đã cọc 345.000 (50% tiền bánh, đủ điều kiện xác nhận đơn).

Hai quy ước quan trọng trong ví dụ:

• Tiền là số nguyên VNĐ (690000), không viết "690.000đ" hay 690000.0. Định dạng hiển thị là việc của giao diện.
• Thời gian là chuỗi theo chuẩn ISO 8601 kèm múi giờ: "2026-10-13T15:00:00+07:00" nghĩa là 15 giờ ngày 13/10/2026 giờ Việt Nam. JSON không có kiểu ngày giờ riêng; nếu bỏ phần +07:00, hệ thống khác có thể hiểu nhầm thành giờ quốc tế và bánh được giao lệch 7 tiếng.

Lỗi JSON thường gặp và thông báo tương ứng

JSON khắt khe hơn TypeScript. Bốn lỗi phổ biến nhất, kèm thông báo bạn sẽ thấy (trong Node.js và các trình duyệt dựa trên Chromium, tại thời điểm viết):

Và một lỗi cực kỳ phổ biến khi làm việc với API:

SyntaxError: Unexpected token '<', "<!DOCTYPE "... is not valid JSON

Dịch: code chờ nhận JSON, nhưng server trả về một trang HTML (bắt đầu bằng <!DOCTYPE). Thường gặp khi gọi sai địa chỉ (server trả trang lỗi 404 dạng HTML), chưa đăng nhập (bị chuyển sang trang đăng nhập), hoặc server gặp lỗi 500 và trả trang báo lỗi. Gặp lỗi này, đừng sửa phần đọc JSON; hãy kiểm tra URL và mã trạng thái của request trước.

Cách tốt nhất để hiểu API là tự gọi một lần. Bạn không cần viết chương trình.

Dùng curl trong terminal

curl là công cụ dòng lệnh gửi request HTTP, có sẵn trên macOS, hầu hết bản Linux, và Windows 10/11. Thử gọi API công khai của GitHub, lấy thông tin một tài khoản mẫu, không cần key:

# macOS / Linux
curl https://api.github.com/users/octocat

# Thêm -i để xem cả mã trạng thái và header
curl -i https://api.github.com/users/octocat

# Windows PowerShell: gõ curl.exe để dùng đúng curl
# (trong Windows PowerShell 5.1, "curl" là tên gọi tắt của một lệnh khác)
curl.exe -i https://api.github.com/users/octocat

Bạn sẽ thấy dòng HTTP/2 200 (hoặc tương tự), các header, rồi một khối JSON chứa tên, số repo, ngày tạo tài khoản. Hãy thử sửa octocat thành một tên không tồn tại và xem mã trạng thái đổi thành 404.

Khi Mộc OMS chạy trên máy, agent có thể dùng curl để kiểm chứng API vừa viết, ví dụ:

# Gửi đơn mới (nội dung lấy từ file don-moi.json) tới server đang chạy trên máy
curl -i -X POST http://localhost:3000/api/orders \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OMS_TEST_TOKEN" \
  -d @don-moi.json

Đọc lệnh: -X POST là method, -H thêm header, -d @don-moi.json lấy body từ file, $OMS_TEST_TOKEN là token đọc từ biến môi trường thay vì gõ thẳng (bài sau sẽ giải thích). Dấu \ ở cuối dòng chỉ để viết một lệnh dài trên nhiều dòng (cú pháp macOS/Linux).

Công cụ có giao diện

Nếu thích bấm nút hơn gõ lệnh, có nhiều công cụ giao diện để gửi request và xem response đẹp mắt, như Postman, Insomnia, Bruno, Hoppscotch, hoặc tiện ích mở rộng trong VS Code. Tính năng và chính sách giá thay đổi theo thời gian; hãy xem trang chính thức tại thời điểm bạn dùng. Với người mới, chúng giúp nhìn thấy rõ bốn phần của request: method, URL, header, body.