Mở đầu — vì sao bài này quan trọng
Hãy hình dung tình huống này: bạn vừa chuyển từ Marketing sang BA, đang ngồi trong một buổi refinement của đội phát triển ví điện tử. Dev hỏi: "Chị ơi, API lấy số dư ví trả về balance theo đơn vị đồng hay xu? Có cần truyền Authorization header không? Khi tài khoản bị khoá thì trả về 403 hay 200 với status: locked?". Cả phòng nhìn bạn. Và bạn nhận ra: tất cả những câu hỏi đó đáng lẽ phải nằm trong tài liệu requirements mà bạn viết — nhưng bạn còn chưa hiểu API là gì.
Đây là khoảnh khắc khiến rất nhiều marketer-chuyển-BA hoảng loạn. Bạn nghĩ "API là việc của dev, mình không code thì cần gì biết". Sai lầm này khiến bạn bị loại khỏi 70% các cuộc thảo luận kỹ thuật quan trọng nhất của một dự án phần mềm hiện đại. Sự thật là: một sản phẩm số ngày nay không phải một khối liền, mà là hàng chục hệ thống nhỏ "nói chuyện" với nhau qua API. Đăng nhập bằng Google, thanh toán qua MoMo, gửi OTP qua SMS, tra cứu địa chỉ qua API bưu chính — mỗi cái là một API. BA chính là người mô tả hai hệ thống cần trao đổi cái gì với nhau, theo điều kiện nào, và khi nào thì lỗi.
Tin tốt: bạn không cần biết code để làm tốt việc này. Bạn cần biết đọc API documentation và biết viết API requirements ở mức nghiệp vụ. Bài này dạy bạn đúng hai kỹ năng đó — không hơn, không kém — để bạn tự tin ngồi vào bàn với dev mà không bị "ngợp".
Khái niệm cốt lõi
API là gì, giải thích cho người không code
API (Application Programming Interface) là cách hai phần mềm giao tiếp với nhau theo một "hợp đồng" được quy ước trước. Ví dụ dễ nhất: nhà hàng. Bạn (hệ thống A) không vào bếp nấu. Bạn đưa order cho người phục vụ (API), người phục vụ mang vào bếp (hệ thống B), bếp nấu rồi trả món ăn ra. Bạn không cần biết bếp nấu thế nào — bạn chỉ cần biết gọi món gì thì ra món đó. Menu chính là API documentation: nó liệt kê bạn được gọi gì, cần cung cấp thông tin gì (size, độ cay), và sẽ nhận lại gì.
Trong web hiện nay, kiểu API phổ biến nhất BA gặp là REST API, hoạt động trên giao thức HTTP — chính là thứ trình duyệt dùng để tải trang web.
Bốn thành phần một BA phải đọc được
Khi nhìn vào một API, hãy luôn tìm bốn thứ:
1. Endpoint và Method (gọi cái gì, theo cách nào)
Endpoint là "địa chỉ" của chức năng, ví dụ /api/v1/wallet/balance. Đi kèm là HTTP method thể hiện ý định:
GET— lấy dữ liệu (xem số dư, xem danh sách đơn).POST— tạo mới (tạo giao dịch, đăng ký user).PUT/PATCH— cập nhật (sửa hồ sơ).DELETE— xoá (huỷ đơn).
2. Request (gửi đi cái gì) Đây là dữ liệu bạn truyền vào, gồm hai phần BA hay đụng tới:
- Parameters/Body: ví dụ tạo giao dịch cần
amount,receiver_id,note. - Headers: thông tin "phụ" như
Authorization(token chứng minh bạn là ai). Đây là chỗ "bảo mật" hay nằm.
"tên": giá_trị. Ví dụ:
{
"balance": 1500000,
"currency": "VND",
"status": "active"
}
balance: 1500000 ở trên là 1,5 triệu đồng hay 15.000 đồng? Chính sự mơ hồ này gây bug tiền tỉ.4. Status code (thành công hay thất bại) Mỗi lần gọi API, hệ thống trả về một mã ba chữ số:
- 2xx (200, 201): thành công.
- 4xx (400, 401, 403, 404): lỗi do phía gọi — sai dữ liệu, chưa đăng nhập, không có quyền, không tìm thấy.
- 5xx (500, 503): lỗi do hệ thống bên kia "sập".
Vì sao đây là việc của BA, không phải dev
Dev quyết định API được xây dựng kỹ thuật thế nào. BA quyết định API phải phục vụ nghiệp vụ gì: dữ liệu nào bắt buộc, quy tắc validate ra sao, lỗi nào cần thông báo gì cho user. Nếu bạn để dev tự quyết, họ sẽ chọn phương án dễ code nhất — không phải phương án đúng với nhu cầu kinh doanh.
Tình huống thực tế
Ví dụ 1 — Tích hợp thanh toán MoMo cho sàn thương mại điện tử Sapo
Một bạn BA tên Trang, xuất thân từ Marketing performance, được giao viết requirements tích hợp cổng thanh toán MoMo vào một nền tảng bán hàng. Ban đầu Trang chỉ viết: "Khi khách bấm thanh toán, hệ thống gọi MoMo để trừ tiền". Dev đọc xong hỏi dồn 12 câu mà Trang trả lời được... 3 câu.
Sau khi học cách đọc API doc của MoMo, Trang viết lại. Cô phát hiện luồng thanh toán MoMo thực ra có ba lời gọi API, không phải một:
POST /create— tạo đơn thanh toán, gửiamount,orderId,redirectUrl. MoMo trả vềpayUrlđể chuyển hướng khách.- Khách thanh toán trên app MoMo (ngoài tầm kiểm soát của hệ thống).
- MoMo gọi ngược lại (gọi là IPN — Instant Payment Notification, một dạng callback API) tới
POST /momo-callbackcủa sàn để báo "đơn 12345 đã trả thành công, mã giao dịch ABC".
redirectUrl, vì khách có thể đóng app sau khi trả tiền". Chính một dòng này đã chặn được lỗ hổng kinh điển: khách trả tiền nhưng đơn không cập nhật, hoặc tệ hơn, kẻ gian giả redirectUrl để chiếm hàng mà chưa trả tiền. Trang không viết một dòng code nào, nhưng cô đã định nghĩa đúng quy tắc nghiệp vụ trên API — đó là giá trị của BA.Ví dụ 2 — Field mơ hồ làm lệch số tiền tại một fintech Việt
Một startup cho vay tiêu dùng (gọi là FinX) tích hợp API chấm điểm tín dụng từ đối tác. API trả về { "score": 720, "limit": 50 }. Đội dev hiểu limit: 50 là 50 triệu đồng và code hạn mức cho vay 50.000.000đ. Nhưng đối tác lại định nghĩa limit theo đơn vị triệu đồng dạng số nguyên là 50, đúng — trừ trường hợp khách hạng VIP thì limit trả về theo đơn vị đồng (50000000). API doc không nói rõ; BA cũng không hỏi.
Kết quả: 3% khách VIP được duyệt hạn mức 50 đồng thay vì 50 triệu, đơn bị từ chối hàng loạt, bộ phận chăm sóc khách hàng "cháy máy" trong hai ngày. Khi truy nguyên, lỗi không nằm ở code — nằm ở API documentation thiếu định nghĩa đơn vị và data type cho field limit.
Bài học: BA phải lập data dictionary cho mọi field quan trọng — tên field, kiểu dữ liệu, đơn vị, giá trị mẫu, ràng buộc. Một dòng "limit: số nguyên, đơn vị triệu đồng, tối đa 500" sẽ tiết kiệm cho FinX hai ngày khủng hoảng.
Ví dụ 3 — Đặc tả lỗi cho tính năng OTP tại một ngân hàng số
Tại một ngân hàng số ở TP.HCM, BA tên Huy đặc tả API gửi OTP đăng nhập. Lần đầu anh chỉ mô tả "case thành công": gọi POST /otp/send, trả 200, gửi mã về điện thoại. Khi demo, đội QA hỏi: "Thế nếu user spam nút gửi 20 lần/phút thì sao? Nếu số điện thoại không tồn tại? Nếu nhà mạng chậm?".
Huy nhận ra mình mới đặc tả 30% công việc. Anh bổ sung bảng status code:
200— gửi thành công.429 Too Many Requests— quá 3 lần trong 60 giây → user thấy "Bạn đã yêu cầu quá nhiều lần, vui lòng đợi 1 phút".404— SĐT không tồn tại trong hệ thống → vì lý do bảo mật vẫn hiển thị "Mã đã được gửi nếu số hợp lệ" (không tiết lộ SĐT có tồn tại hay không).503— lỗi nhà mạng → "Hệ thống đang bận, vui lòng thử lại".
Hướng dẫn từng bước
Khi cần làm việc với một API trong dự án, hãy theo quy trình 6 bước sau.
Bước 1 — Xác định nghiệp vụ cần gì trước, kỹ thuật sau. Đừng vội mở API doc. Hỏi: chức năng này phục vụ user làm gì? Dữ liệu nào người dùng nhìn thấy/nhập vào? Ví dụ "khách xem lịch sử giao dịch 30 ngày gần nhất, lọc theo loại".
Bước 2 — Đọc API documentation theo bốn thành phần. Lần lượt tìm: Endpoint + Method → Request (params, headers) → Response (các field) → Status codes. Nếu là API có sẵn (Google, MoMo, VNPay), tài liệu thường ở dạng Swagger/OpenAPI hoặc Postman — bạn chỉ cần đọc, không cần dựng.
Bước 3 — Lập data dictionary cho Request và Response. Với mỗi field, ghi: tên, kiểu dữ liệu (số/chuỗi/boolean/ngày), bắt buộc hay không, đơn vị, giá trị mẫu, ràng buộc. Đây là phần giá trị nhất bạn đóng góp.
Bước 4 — Đặc tả happy path + tất cả error case. Liệt kê mọi status code có thể xảy ra và thông báo người dùng tương ứng. Tự hỏi "nếu... thì sao?" cho mọi trường hợp xấu.
Bước 5 — Vẽ luồng trao đổi (sequence) nếu có nhiều bước. Với các tích hợp như thanh toán (create → redirect → callback), một sơ đồ đơn giản "ai gọi ai, theo thứ tự nào" giúp cả đội hiểu nhanh hơn ngàn dòng chữ.
Bước 6 — Rà soát cùng dev và đối tác. Đưa đặc tả cho dev xem có khả thi không, đưa cho đối tác cung cấp API xác nhận bạn hiểu đúng. Một buổi review 30 phút tiết kiệm hàng tuần làm lại.
Lỗi thường gặp & mẹo
Lỗi 1 — Tưởng API là chuyện của dev nên không tham gia. Hậu quả: requirements thiếu, dev tự quyết theo hướng dễ code. Mẹo: bạn không cần hiểu cách API được lập trình, chỉ cần hiểu API trao đổi dữ liệu nghiệp vụ gì.
Lỗi 2 — Bỏ qua data type và đơn vị của field. Đây là lỗi đắt nhất (xem ví dụ FinX). Mẹo: với mọi con số liên quan tiền, thời gian, số lượng — luôn ghi rõ đơn vị.
Lỗi 3 — Chỉ đặc tả happy path. Mẹo: quy ước với bản thân rằng mỗi endpoint phải có tối thiểu 3 case lỗi được mô tả thông báo cho user.
Lỗi 4 — Không quan tâm phân trang (pagination). API trả danh sách (giao dịch, đơn hàng) gần như không bao giờ trả hết một lúc. Mẹo: luôn hỏi "danh sách này trả tối đa bao nhiêu bản ghi mỗi lần, lấy trang tiếp theo thế nào?".
Lỗi 5 — Nhầm lẫn ai gọi ai trong callback. Với webhook/IPN, hệ thống bên ngoài chủ động gọi vào hệ thống của bạn. Mẹo: vẽ mũi tên chỉ rõ chiều gọi.
Mẹo vàng: Hãy xin quyền truy cập Postman hoặc trang Swagger của dự án và tự "bấm thử" một lời gọi GET đơn giản. Nhìn thấy JSON trả về tận mắt sẽ giúp bạn hiểu API nhanh gấp mười lần đọc lý thuyết. Bạn không phá hỏng gì cả với một lệnh GET.
Bài tập thực hành
- Đọc một API thật: Mở tài liệu API công khai của VNPay hoặc MoMo (phần "Tạo đơn thanh toán"). Liệt kê đủ bốn thành phần: endpoint, method, ít nhất 5 field request, 5 field response, và 3 status code.
- Lập data dictionary: Cho response giả định
{ "user_id": 88, "name": "Lan", "balance": 250000, "vip": true, "joined": "2026-01-15" }. Lập bảng mô tả từng field: tên, kiểu dữ liệu, đơn vị (nếu có), giải thích nghiệp vụ.
- Đặc tả error case: Với API "đặt vé xem phim" (
POST /booking), hãy viết ít nhất 4 trường hợp lỗi (hết ghế, hết thời gian giữ ghế, thanh toán thất bại, chưa đăng nhập) kèm status code phỏng đoán và thông báo hiển thị cho user.
- Vẽ sequence: Vẽ sơ đồ luồng 3 bước của một tích hợp thanh toán (tạo đơn → khách trả → callback xác nhận), ghi rõ ai gọi ai.
Tóm tắt
API là cách hai hệ thống "nói chuyện" với nhau, và trong sản phẩm số hiện đại, BA chính là người mô tả chúng cần trao đổi cái gì, theo điều kiện nào, và xử lý lỗi ra sao — dù bạn không viết một dòng code. Hãy ghi nhớ bốn thành phần phải đọc được: Endpoint + Method, Request, Response, Status code. Giá trị lớn nhất bạn đóng góp nằm ở ba việc: lập data dictionary rõ ràng (đặc biệt là kiểu dữ liệu và đơn vị), đặc tả đầy đủ các trường hợp lỗi kèm thông báo cho người dùng, và vẽ rõ luồng trao đổi trong các tích hợp nhiều bước. Ba câu chuyện MoMo, FinX và OTP đều cho thấy: sự cố nghiêm trọng nhất thường không đến từ code sai, mà từ requirements API mơ hồ. Nền tảng Marketing của bạn — tư duy trải nghiệm người dùng, viết copy cho từng tình huống — chính là lợi thế giúp bạn đặc tả phần error case và thông báo tốt hơn nhiều BA thuần kỹ thuật. Đừng sợ API; hãy coi nó là một loại "hợp đồng giao tiếp" mà bạn — người hiểu nghiệp vụ nhất — có quyền và có trách nhiệm định nghĩa.