Bạn viết requirement:
“Khi user bấm Thanh toán, hệ thống xử lý giao dịch.”
Nghe có vẻ ổn.
Nhưng dev sẽ hỏi ngay:
App gửi những data gì lên server?
Server trả về gì nếu thanh toán thành công?
Nếu thanh toán thất bại thì sao?
Nếu Payment Gateway timeout thì xử lý thế nào?
Có tạo order trước hay payment trước?
=> Lúc này bạn mới nhận ra:
Một cái nút trên UI không chỉ là một cái nút.
Đằng sau nó là cả một cuộc “nói chuyện” giữa nhiều hệ thống.
Và cuộc nói chuyện đó thường diễn ra qua API.
API là gì? Giải thích kiểu BA dễ hiểu
API là cách các hệ thống giao tiếp với nhau.
Hiểu đơn giản:
API giống như “người phục vụ” đứng giữa app và hệ thống backend.
User bấm nút trên app
=> App gửi yêu cầu đến backend
=> Backend xử lý
=> Backend trả kết quả về app
=> App hiển thị kết quả cho user
Ví dụ đời thường:
Bạn vào quán gọi món.
Bạn nói:
“Cho tôi 1 ly cà phê sữa đá.”
Người phục vụ nhận yêu cầu
=> chuyển vào bếp/quầy pha chế
=> nhận kết quả
=> mang đồ uống ra cho bạn
Trong hệ thống:
User bấm nút
=> App gửi request
=> API nhận và xử lý
=> Trả response
=> UI hiển thị kết quả
Request là gì?
Request = yêu cầu được gửi đi.
Ví dụ user bấm “Thanh toán”, app có thể gửi lên Payment API:
{
"orderId": "ORD123",
"userId": "U001",
"amount": 500000,
"paymentMethod": "BANK_TRANSFER"
}
BA cần hiểu trong request có:
Field nào được gửi?
Field nào bắt buộc?
Data type là gì?
Giá trị có giới hạn không?
Field nào do user nhập, field nào system tự sinh?
Ví dụ:
orderId: mã đơn hàng
userId: user thực hiện thanh toán
amount: số tiền thanh toán
paymentMethod: phương thức thanh toán
Nếu BA không làm rõ request, dev sẽ phải đoán.
Mà dev đoán thì rất dễ lệch requirement.
Response là gì?
Response = kết quả hệ thống trả về.
Nếu thanh toán thành công, Payment API có thể trả:
{
"status": "SUCCESS",
"transactionId": "TXN789",
"paidAt": "2026-05-16T10:30:00"
}
App nhận response này
=> hiển thị màn hình “Thanh toán thành công”
=> cập nhật trạng thái đơn hàng
=> gửi thông báo cho user
BA cần làm rõ:
Thành công thì trả gì?
UI hiển thị gì?
Status nào được coi là thành công?
Có lưu transaction ID không?
Có gửi notification không?
Error Response là phần Fresher BA hay bỏ quên nhất
Nhiều BA chỉ viết happy flow:
User bấm Thanh toán
=> Thanh toán thành công
=> Done
Nhưng thực tế hệ thống có thể lỗi rất nhiều kiểu:
Số dư không đủ
Thẻ hết hạn
Payment Gateway timeout
Order không tồn tại
User bấm thanh toán 2 lần
Backend lỗi
Network mất kết nối
Vì vậy, BA cần define cả error response.
Ví dụ:
{
"status": "FAILED",
"errorCode": "INSUFFICIENT_BALANCE",
"message": "Số dư không đủ để thực hiện giao dịch"
}
Hoặc:
{
"status": "PENDING",
"errorCode": "PAYMENT_TIMEOUT",
"message": "Giao dịch đang được xử lý. Vui lòng kiểm tra lại sau."
}
Điểm quan trọng:
Không phải lỗi nào cũng hiển thị chung một câu “Có lỗi xảy ra”.
Với user, mỗi lỗi cần cách xử lý khác nhau.
Với system, mỗi lỗi có thể kéo theo logic khác nhau.
Vì sao BA cần hiểu API?
1️⃣ Để viết requirement rõ hơn
Thay vì viết:
“Hệ thống xử lý thanh toán.”
Hãy viết rõ:
Input là gì?
Output là gì?
Success case là gì?
Error case là gì?
Rule xử lý từng status là gì?
2️⃣ Để làm việc tốt hơn với Dev
Khi hiểu API, bạn sẽ nói chuyện với dev rõ hơn:
“Field này required hay optional?”
“Response có trả transactionId không?”
“Nếu timeout thì status là PENDING hay FAILED?”
“Error code này FE cần map message như thế nào?”
=> Dev sẽ thấy bạn hiểu system, không chỉ viết mô tả UI.
3️⃣ Để test đúng hơn
BA hiểu API sẽ biết:
Không chỉ test trên màn hình
Cần check data request/response
Cần test lỗi
Cần verify trạng thái sau khi API trả kết quả
Ví dụ UI báo “Thanh toán thành công” nhưng backend trả PENDING
=> Đây là bug nghiêm trọng.
4️⃣ Để tránh requirement bị hổng
Một requirement API bị hổng thường thiếu:
Required field
Validation rule
Error response
Timeout handling
Retry logic
Status mapping
Data lưu vào DB
Notification sau xử lý
Đây là những thứ nếu không define sớm, đến UAT mới lòi ra rất đau.
