Mở đầu — vì sao bài này quan trọng
Có một sự thật mà nhiều bạn fresher không nhận ra: đến năm 2026, phần lớn tính năng mới trong các sản phẩm phần mềm không còn được "xây từ đầu" nữa. Thay vào đó, chúng được ghép lại từ các dịch vụ bên ngoài thông qua API. Muốn thanh toán? Gọi API của VNPay, MoMo, hoặc Stripe. Muốn gửi SMS OTP? Gọi API của Twilio hoặc eSMS. Muốn xác thực khuôn mặt eKYC? Gọi API của FPT.AI hoặc VNPT. Muốn hiển thị bản đồ? Google Maps API. Ước tính không quá lời rằng khoảng 70% feature mà một BA junior gặp trong công việc thực tế đều dính líu đến ít nhất một API bên thứ ba.
Vậy tại sao điều này lại quan trọng với bạn — một người mới, không code, chỉ viết tài liệu? Bởi vì khi spec (tài liệu đặc tả) của bạn không mô tả rõ phần integration, developer buộc phải đoán. Họ đoán field nào là bắt buộc, đoán khi lỗi thì màn hình hiển thị gì, đoán timeout bao lâu thì báo thất bại. Và mỗi lần dev đoán sai là một bug, một vòng rework, một buổi họp căng thẳng nơi ai đó hỏi "sao không có trong spec?". Câu trả lời "em không biết API hoạt động thế nào" sẽ khiến bạn mất điểm nghiêm trọng.
Chưa kể, trong phỏng vấn BA, câu hỏi "em hiểu API là gì không?" hoặc "vẽ giúp anh flow tích hợp thanh toán" gần như là câu tủ. Bài này sẽ giúp bạn — dù không phải dân kỹ thuật — hiểu đủ sâu về API và integration để viết spec đúng, đặt câu hỏi đúng, và tự tin khi ngồi vào bàn phỏng vấn. Bạn không cần biết code. Bạn cần biết cách tư duy về luồng dữ liệu giữa các hệ thống.
Khái niệm cốt lõi
API là gì — giải thích không cần code
API (Application Programming Interface) là cách hai phần mềm nói chuyện với nhau. Hãy tưởng tượng bạn vào một nhà hàng. Bạn không xông thẳng vào bếp để tự nấu. Bạn gọi món qua người phục vụ (waiter). Người phục vụ nhận yêu cầu của bạn theo một quy tắc rõ ràng (menu), mang xuống bếp, rồi bưng món ăn ra. API chính là người phục vụ đó: hệ thống của bạn gửi một request (yêu cầu) theo đúng "menu" mà API quy định, hệ thống bên kia xử lý và trả về một response (phản hồi).
Cái "menu" ở đây gọi là API contract (hợp đồng API) hoặc API documentation. Nó ghi rõ: bạn được gọi những gì, phải gửi thông tin nào, và sẽ nhận lại gì. Là BA, phần lớn công việc của bạn xoay quanh việc đọc, hiểu và diễn giải cái "menu" này thành yêu cầu nghiệp vụ.
Request và Response — cấu trúc cần nắm
Một request thường gồm bốn phần mà BA nên nhận diện được:
- Endpoint: địa chỉ của API, ví dụ
https://api.momo.vn/v2/payment/create. Giống như địa chỉ nhà. - Method (HTTP verb): hành động muốn làm.
GETlà lấy dữ liệu (xem thông tin đơn hàng),POSTlà tạo mới (tạo giao dịch),PUT/PATCHlà cập nhật,DELETElà xóa. Bạn chỉ cần nhớ GET để đọc, POST để tạo — thế là đủ dùng 80% trường hợp. - Header: thông tin đi kèm, quan trọng nhất là phần xác thực (authentication) như API key hoặc token.
- Body / Payload: dữ liệu gửi đi, thường ở định dạng JSON.
2xx (như 200, 201) là thành công; 4xx (như 400, 401, 404) là lỗi từ phía người gọi — sai dữ liệu, sai key, không tìm thấy; 5xx (như 500, 503) là lỗi từ phía server bên kia. Vì sao BA cần biết? Vì mỗi status code sẽ tương ứng với một hành vi trên màn hình mà bạn phải đặc tả: 200 thì hiện "Thanh toán thành công", 400 thì hiện "Thông tin không hợp lệ", 500 thì hiện "Hệ thống đang bận, vui lòng thử lại".JSON — định dạng bạn phải đọc được
JSON là cách dữ liệu được đóng gói. Đừng sợ nó. Về bản chất nó chỉ là các cặp "tên: giá trị". Ví dụ một response tạo đơn hàng:
{
"orderId": "DH2026061501",
"amount": 250000,
"currency": "VND",
"status": "PENDING",
"customer": {
"name": "Nguyen Van A",
"phone": "0901234567"
}
}
Bạn cần đọc được: đơn hàng này mã DH2026061501, số tiền 250.000đ, trạng thái đang chờ. Kỹ năng đọc JSON quan trọng vì khi bạn viết acceptance criteria hay data mapping, bạn phải biết field nào tên gì, kiểu dữ liệu ra sao, có bắt buộc không.
Integration — bức tranh lớn
Integration (tích hợp) là khi hệ thống của bạn kết nối với một hoặc nhiều hệ thống khác để tạo thành một luồng nghiệp vụ hoàn chỉnh. Có hai kiểu giao tiếp BA hay gặp:
- Synchronous (đồng bộ): gọi và chờ trả lời ngay, như gọi điện thoại. Ví dụ kiểm tra số dư tài khoản.
- Asynchronous (bất đồng bộ) / Webhook: gọi xong không chờ, hệ thống kia xử lý xong sẽ "gọi ngược lại" báo kết quả, như nhắn tin rồi chờ hồi âm. Thanh toán qua MoMo là ví dụ kinh điển: bạn tạo giao dịch, người dùng chuyển sang app MoMo trả tiền, rồi MoMo mới gọi webhook (IPN – Instant Payment Notification) về hệ thống của bạn để xác nhận. Nhiều fresher quên mất luồng webhook này và spec bị thủng ngay chỗ quan trọng nhất.
Tình huống thực tế
Ví dụ 1 — Sàn thương mại điện tử tích hợp thanh toán MoMo
Một sàn TMĐT tầm trung tại TP.HCM (giả định tên "ChợViệt") giao cho team một feature: cho phép khách thanh toán đơn hàng qua ví MoMo. BA fresher trong team, bạn Linh, viết user story gọn lỏn: "Là khách hàng, tôi muốn thanh toán bằng MoMo để không phải nhập thẻ." Rồi hết.
Khi dev bắt tay làm, hàng loạt câu hỏi bật ra mà spec không trả lời: Sau khi khách bấm "Thanh toán MoMo", chuyển sang app MoMo hay quét QR? Nếu khách trả tiền thành công nhưng mạng rớt trước khi quay lại sàn thì đơn hàng ở trạng thái gì? MoMo gửi webhook xác nhận về đâu, và nếu webhook đến trễ 5 phút thì đơn có bị hủy không? Nếu khách trả tiền hai lần thì sao?
Kết quả: feature trễ hai tuần, có một khách thật trả tiền nhưng đơn vẫn hiện "chưa thanh toán" vì team không xử lý webhook đúng, gây khiếu nại. Bài học: khi tích hợp thanh toán, spec bắt buộc phải mô tả cả ba luồng — luồng thành công, luồng thất bại, và luồng webhook xác nhận bất đồng bộ. Trạng thái đơn hàng (PENDING → PAID → FAILED) phải được vẽ rõ như một state machine. Một câu user story không bao giờ đủ cho integration.
Ví dụ 2 — Ứng dụng ngân hàng số tích hợp eKYC
Tại một ngân hàng số (giả định "NeoBank"), team làm tính năng mở tài khoản online. Họ tích hợp API eKYC của FPT.AI để đọc thông tin từ CCCD và so khớp khuôn mặt. BA phụ trách là bạn Huy, có kinh nghiệm 6 tháng.
Huy làm một việc rất đúng: anh xin bằng được API documentation của FPT.AI và đọc kỹ. Anh phát hiện API trả về một field confidence (độ tin cậy so khớp khuôn mặt) từ 0 đến 1. Câu hỏi nghiệp vụ ngay lập tức nảy ra: ngưỡng bao nhiêu thì coi là "khớp"? 0.8 hay 0.9? Nếu 0.75 thì cho qua, từ chối, hay chuyển sang duyệt thủ công? Đây không phải câu hỏi kỹ thuật — đây là business rule mà chỉ nghiệp vụ mới quyết được. Huy mang câu hỏi này lên họp với bộ phận rủi ro và thống nhất: dưới 0.85 thì đẩy sang nhân viên duyệt tay.
Bài học: API không chỉ là chuyện kỹ thuật. Đằng sau mỗi field trả về thường ẩn một quyết định nghiệp vụ. BA giỏi là người đọc được response, phát hiện những "điểm cần ra quyết định" đó, và biến chúng thành business rule rõ ràng trong spec. Nếu Huy bỏ qua field confidence, dev sẽ tự chọn một ngưỡng ngẫu nhiên và ngân hàng có thể mở nhầm tài khoản cho kẻ giả mạo.
Ví dụ 3 — Câu hỏi phỏng vấn thật
Trong một buổi phỏng vấn BA junior tại một công ty outsourcing ở Hà Nội, ứng viên được đưa tình huống: "Hệ thống của chúng tôi gọi API đối tác để lấy tỷ giá ngoại tệ, cập nhật mỗi 15 phút. Em hãy nêu những trường hợp cần xử lý." Ứng viên A chỉ nói "gọi API lấy tỷ giá rồi hiển thị". Ứng viên B nói: "Cần xử lý khi API đối tác không phản hồi (timeout) thì dùng tỷ giá cũ hay báo lỗi; khi API trả về status 500 thì retry mấy lần; khi dữ liệu trả về thiếu một loại tiền tệ thì làm gì; và cần định nghĩa tỷ giá 'cũ tối đa bao lâu' còn được phép dùng."
Ứng viên B được nhận. Bài học: tư duy về integration của một BA thể hiện rõ nhất ở việc bạn nghĩ được đến các luồng lỗi và trường hợp biên (edge case), chứ không chỉ luồng "mọi thứ suôn sẻ" (happy path). Đây là điểm phân biệt fresher biết việc và fresher chỉ học vẹt.
Hướng dẫn từng bước
Đây là quy trình bạn có thể áp dụng ngay khi được giao một feature có tích hợp API:
Bước 1 — Xác định có bao nhiêu hệ thống tham gia. Vẽ ra: hệ thống của bạn, và các hệ thống bên ngoài (payment gateway, SMS, eKYC...). Mỗi mũi tên giữa chúng là một điểm tích hợp cần đặc tả.
Bước 2 — Xin và đọc API documentation. Đây là bước quan trọng nhất mà fresher hay bỏ. Chủ động hỏi dev hoặc đối tác: "Cho em xin tài liệu API." Đọc để nắm: có những endpoint nào, mỗi cái nhận gì trả gì, cơ chế xác thực ra sao, có webhook không.
Bước 3 — Vẽ sequence diagram hoặc luồng đơn giản. Không cần đẹp, chỉ cần thể hiện: ai gọi ai, theo thứ tự nào, dữ liệu gì đi qua. Công cụ đơn giản như draw.io là đủ. Đây là deliverable mà dev rất trân trọng.
Bước 4 — Lập bảng data mapping. Với mỗi field, ghi rõ: tên field bên hệ thống mình, tên field tương ứng bên API, kiểu dữ liệu, bắt buộc hay không, quy tắc chuyển đổi (ví dụ: ngày tháng định dạng dd/MM/yyyy bên mình nhưng API cần yyyy-MM-dd).
Bước 5 — Đặc tả đầy đủ ba nhóm luồng. Happy path (thành công), error path (mọi loại lỗi 4xx, 5xx, timeout), và edge case (dữ liệu thiếu, gọi trùng, phản hồi trễ).
Bước 6 — Định nghĩa business rule ẩn trong response. Rà từng field trả về và tự hỏi: "Field này ảnh hưởng đến quyết định nghiệp vụ nào?"
Bước 7 — Viết acceptance criteria kiểm chứng được. Ví dụ: "Khi API thanh toán trả status FAILED, hệ thống hiển thị thông báo 'Giao dịch thất bại' và giữ đơn hàng ở trạng thái PENDING trong 30 phút."
Lỗi thường gặp & mẹo
Lỗi 1 — Chỉ viết happy path. Đây là lỗi số một. Spec chỉ mô tả khi mọi thứ thành công. Mẹo: với mỗi bước gọi API, luôn tự hỏi "nếu bước này fail thì sao?".
Lỗi 2 — Bỏ quên webhook / luồng bất đồng bộ. Nhất là với thanh toán. Mẹo: hỏi ngay "kết quả cuối cùng được xác nhận qua đâu — response trực tiếp hay webhook?".
Lỗi 3 — Không định nghĩa timeout và retry. API bên thứ ba có thể chậm hoặc chết. Mẹo: luôn hỏi "timeout bao lâu? Có retry không? Retry mấy lần?".
Lỗi 4 — Nhầm lẫn giữa lỗi kỹ thuật và lỗi nghiệp vụ. Status 400 (dữ liệu sai) khác với "khách không đủ số dư" (status có thể 200 nhưng body báo thất bại nghiệp vụ). Mẹo: phân biệt rõ trong spec hai loại thất bại này vì thông báo cho người dùng khác nhau.
Lỗi 5 — Đọc lướt API documentation. Bỏ sót field bắt buộc dẫn đến rework. Mẹo: đọc từng field trong request bắt buộc, đánh dấu cái nào hệ thống mình chưa có dữ liệu.
Lỗi 6 — Không nghĩ đến idempotency (chống trùng). Nếu người dùng bấm nút hai lần, có tạo hai giao dịch không? Mẹo: hỏi dev về cơ chế chống gọi trùng, thường qua một mã giao dịch duy nhất.
Mẹo vàng: hãy cài Postman (miễn phí) và nhờ dev cho bạn xem một request thật chạy thử. Nhìn tận mắt một request đi và response về sẽ giúp bạn hiểu API nhanh gấp mười lần đọc lý thuyết.
Bài tập thực hành
Bài 1 — Đọc JSON. Cho response sau, hãy trả lời: đơn hàng mã gì, số tiền bao nhiêu, đang ở trạng thái nào, và số điện thoại khách?
{
"orderId": "ORD777",
"totalAmount": 1500000,
"status": "AWAITING_PAYMENT",
"buyer": { "phone": "0987654321" }
}
Bài 2 — Liệt kê luồng lỗi. Cho feature "gửi SMS OTP khi đăng ký qua API eSMS". Hãy liệt kê ít nhất 5 trường hợp cần đặc tả ngoài happy path (gợi ý: số điện thoại sai định dạng, nhà mạng chặn, timeout, hết quota, người dùng nhập sai OTP quá 3 lần).
Bài 3 — Vẽ sequence diagram. Vẽ luồng thanh toán MoMo gồm các bên: Người dùng, Website ChợViệt, MoMo. Nhớ có cả bước webhook IPN xác nhận. Dùng draw.io.
Bài 4 — Tìm business rule ẩn. API tính điểm tín dụng trả về field creditScore (300–850). Hãy đề xuất business rule: mức nào duyệt tự động, mức nào từ chối, mức nào duyệt thủ công.
Bài 5 — Viết acceptance criteria. Viết 3 acceptance criteria theo mẫu Given-When-Then cho tình huống: gọi API thanh toán và API trả về timeout sau 30 giây.
Tóm tắt
API là cách hai phần mềm nói chuyện với nhau, và trong bối cảnh 2026, hầu hết feature đều dựa trên tích hợp API bên thứ ba. Là BA fresher, bạn không cần biết code, nhưng bạn bắt buộc phải hiểu request–response, đọc được JSON, thuộc các status code cơ bản, và nắm được sự khác nhau giữa luồng đồng bộ và webhook bất đồng bộ.
Giá trị lớn nhất bạn mang lại nằm ở chỗ: viết spec integration đầy đủ cả happy path, error path và edge case; phát hiện những business rule ẩn sau mỗi field response; và lập bảng data mapping rõ ràng để dev không phải đoán. Ba tình huống trong bài — thanh toán MoMo, eKYC ngân hàng, và câu hỏi phỏng vấn tỷ giá — đều chỉ ra cùng một điều: BA giỏi phân biệt với BA yếu ở khả năng nghĩ đến những gì có thể sai. Hãy chủ động xin API documentation, cài Postman xem request thật, và luôn tự hỏi "nếu bước này fail thì sao?". Nắm vững tư duy này, bạn sẽ viết được spec mà dev tin tưởng và trả lời trôi chảy mọi câu hỏi integration trong phỏng vấn.