Mở đầu — vì sao bài này quan trọng
Hãy thành thật với nhau một chút. Khi còn làm Sales hay BD, bạn nghe từ "API" được dev hay product nhắc tới và thường gật gù cho qua, vì nó "thuộc về phần kỹ thuật". Nhưng đây chính là điểm khiến rất nhiều ex-Sales bị mắc kẹt khi chuyển sang BA: họ viết requirement rất giỏi về mặt nghiệp vụ, nhưng đến đoạn "tích hợp" thì lúng túng, và buổi họp với dev biến thành buổi dev giải thích lại từ đầu.
Sự thật năm 2026 là thế này: khoảng 90% hệ thống doanh nghiệp hiện đại không hoạt động một mình. Một app gọi xe gọi tới Google Maps để định vị, gọi tới VNPay hoặc MoMo để thanh toán, gọi tới một dịch vụ SMS để gửi OTP. Mỗi "cuộc gọi" đó là một API. Khi khách hàng nói "tôi muốn hệ thống của tôi tích hợp với phần mềm kế toán MISA", thì 99% trường hợp họ đang nói về một API. Và nếu BA không hiểu API là gì, bạn sẽ không thể viết được requirement cho phần quan trọng nhất, đắt tiền nhất, và dễ trễ deadline nhất của dự án.
Tin tốt là: bạn không cần biết code để hiểu API. Bạn chỉ cần hiểu API như một hợp đồng giao tiếp giữa hai hệ thống — và đoán xem, hợp đồng và giao tiếp chính là thứ dân Sales/BD làm cả ngày. Bài này sẽ giúp bạn nói chuyện "tích hợp" một cách tự tin, không bị dev qua mặt, và biến năng lực thương lượng hợp đồng của bạn thành năng lực định nghĩa API spec.
Khái niệm cốt lõi
API là gì, giải thích kiểu không-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 nói với người phục vụ món bạn muốn, người phục vụ truyền vào bếp, bếp nấu xong rồi đưa món ra cho bạn. Người phục vụ chính là API: một cửa được định nghĩa rõ ràng để bạn yêu cầu và nhận lại thứ mình cần, mà không cần biết bếp vận hành ra sao.
Trong đó:
- Request (yêu cầu): bạn gọi món — "cho tôi thông tin khách hàng có mã KH001".
- Response (phản hồi): bếp trả món — hệ thống trả về tên, số điện thoại, lịch sử mua hàng của KH001.
- Endpoint: địa chỉ của "quầy phục vụ", ví dụ
https://api.congty.vn/v1/customers/KH001.
Bốn động từ bạn cần thuộc lòng
Hầu hết API hiện nay theo chuẩn REST, dùng bốn "động từ" tương ứng với bốn thao tác nghiệp vụ quen thuộc:
- GET — lấy dữ liệu (xem thông tin đơn hàng).
- POST — tạo mới (tạo một khách hàng mới).
- PUT/PATCH — cập nhật (sửa địa chỉ giao hàng).
- DELETE — xóa (hủy một đơn hàng).
Request và Response trông như thế nào
Dữ liệu trong API thường được gói dưới định dạng JSON — một cách viết dữ liệu dạng "khóa: giá trị" mà con người vẫn đọc được. Ví dụ, một request tạo đơn hàng:
POST /v1/orders
{
"customer_id": "KH001",
"product_code": "SP200",
"quantity": 2,
"payment_method": "momo"
}
Và response khi thành công:
{
"order_id": "DH9981",
"status": "confirmed",
"total": 480000,
"created_at": "2026-06-27T10:15:00"
}
Bạn không cần viết được đoạn này, nhưng bạn cần đọc hiểu nó. Vì khi BA định nghĩa một API, về bản chất bạn đang định nghĩa: gửi đi cái gì, nhận về cái gì, và khi lỗi thì thông báo ra sao.
Khi nào API là "trái tim" của requirement
Bất cứ khi nào trong requirement xuất hiện các từ sau, hãy bật đèn báo "đây là chuyện API":
- "đồng bộ với", "tích hợp với", "kết nối tới"
- "tự động đẩy dữ liệu sang", "lấy dữ liệu từ"
- "single sign-on", "đăng nhập bằng tài khoản X"
- "webhook", "callback", "thông báo real-time"
Tình huống thực tế
Tình huống 1 — Tích hợp thanh toán cho một startup giao đồ ăn ở TP.HCM
Một startup giao đồ ăn (gọi là FoodFast) muốn cho khách thanh toán bằng MoMo thay vì chỉ tiền mặt. Sếp viết requirement đúng một dòng: "Tích hợp thanh toán MoMo." Bạn BA mới chuyển từ BD sang nhận task này.
Nếu hiểu API, bạn sẽ biết "một dòng" đó thực chất ẩn chứa cả một loạt câu hỏi phải làm rõ với MoMo và với dev:
- Khi khách bấm "Thanh toán MoMo", hệ thống FoodFast gọi API nào của MoMo để tạo giao dịch? Cần gửi đi gì (số tiền, mã đơn, mô tả)?
- Khách trả tiền xong, FoodFast biết bằng cách nào? Câu trả lời: MoMo gọi webhook về FoodFast với trạng thái
successhoặcfailed. - Nếu webhook bị rớt mạng thì sao? Cần một API "hỏi lại trạng thái giao dịch" để đối soát.
- Lỗi thường gặp: số dư không đủ, hết hạn giao dịch, khách hủy — mỗi lỗi cần một thông báo riêng cho người dùng.
Tình huống 2 — Sales-led integration tại một công ty SaaS HR ở Việt Nam
Một công ty SaaS làm phần mềm chấm công (giả định tên Tanca-style). Đội Sales đi bán và liên tục gặp câu hỏi từ khách hàng lớn: "Phần mềm của anh có đẩy được dữ liệu chấm công sang phần mềm tính lương MISA của bên tôi không?" Sales gật đầu để chốt deal, rồi quăng về cho team product.
Đây chính là sales-led product — sản phẩm được định hình bởi nhu cầu tích hợp mà Sales hứa với khách. Một ex-Sales chuyển BA ở đây có lợi thế cực lớn: bạn hiểu vì sao khách cần tích hợp này (để khỏi nhập tay 500 dòng công lương mỗi tháng), bạn hiểu khách sẵn sàng trả thêm bao nhiêu cho nó. Nhưng giờ bạn phải dịch lời hứa đó thành spec:
- MISA cung cấp API nhập bảng công không? Nếu có, định dạng dữ liệu họ nhận là gì?
- Đẩy theo thời gian thực hay theo lô cuối tháng (batch)?
- Ai sở hữu khóa xác thực (API key) — khách tự cấu hình hay mình làm hộ?
Tình huống 3 — Buổi họp grooming khi BA không hiểu API
Một BA cũ làm BD bất động sản, chuyển sang một dự án ví điện tử. Trong buổi grooming, dev hỏi: "Endpoint lấy danh sách giao dịch có cần phân trang không? Mỗi lần trả về tối đa bao nhiêu record?" BA này im lặng, vì không hiểu "phân trang" (pagination) trong ngữ cảnh API là gì.
Kết quả: dev tự quyết trả về 1.000 giao dịch một lần. Đến khi lên production, có khách hàng doanh nghiệp có 50.000 giao dịch — màn hình đơ 8 giây, khách phàn nàn ầm ĩ.
Bài học: BA không cần thiết kế kỹ thuật, nhưng cần đủ "API literacy" để đặt câu hỏi đúng và mang câu hỏi đó về cho stakeholder. Câu "mỗi lần trả về bao nhiêu" thực chất là một câu hỏi nghiệp vụ trá hình: "người dùng thường xem bao nhiêu giao dịch một lúc?". Khi bạn hiểu API, bạn nối được câu hỏi kỹ thuật của dev với câu trả lời nghiệp vụ của khách.
Hướng dẫn từng bước
Đây là quy trình để một BA viết được phần requirement tích hợp/API mà không cần biết code:
Bước 1 — Phát hiện "tín hiệu tích hợp". Đọc lại yêu cầu, khoanh tròn mọi cụm từ kiểu "đồng bộ với", "đăng nhập bằng", "tự động gửi sang". Mỗi cụm đó là một API tiềm năng cần làm rõ.
Bước 2 — Xác định hướng dữ liệu. Hỏi: hệ thống của ta GỌI ra (mình cần dữ liệu của họ) hay hệ thống kia GỌI vào (họ báo cho mình bằng webhook)? Vẽ một mũi tên đơn giản giữa hai hộp. Chỉ riêng việc vẽ đúng chiều mũi tên đã giải quyết một nửa hiểu nhầm.
Bước 3 — Định nghĩa "gửi gì, nhận gì". Với mỗi API, lập bảng 3 cột: Trường dữ liệu | Bắt buộc/Tùy chọn | Ý nghĩa nghiệp vụ. Ví dụ với API tạo đơn: customer_id (bắt buộc, mã khách), voucher_code (tùy chọn, mã giảm giá).
Bước 4 — Liệt kê kịch bản lỗi. Đây là phần ex-Sales hay quên nhưng dev luôn cần. Hỏi: "Điều gì xảy ra khi sai?" Hết hàng, hết hạn token, sai định dạng, mạng rớt giữa chừng. Mỗi lỗi cần một mã và một thông báo cho người dùng cuối.
Bước 5 — Hỏi về xác thực và phân quyền. Hệ thống kia cần API key, token, hay OAuth? Ai cấp? Hết hạn khi nào? Đây là câu hỏi bảo mật bắt buộc, đừng để đến cuối dự án.
Bước 6 — Hỏi về khối lượng và hiệu năng. Bao nhiêu request mỗi giây hệ thống kia cho phép (rate limit)? Một lần trả về tối đa bao nhiêu record (pagination)? Dữ liệu đồng bộ real-time hay theo lô?
Bước 7 — Đọc tài liệu API (API documentation). Mọi dịch vụ nghiêm túc như VNPay, MoMo, Google, Stripe đều có trang docs công khai. Bạn không cần đọc hết — chỉ cần tìm đúng endpoint liên quan, xem ví dụ request/response. Dùng một công cụ như Postman để dev "gọi thử" và cho bạn xem kết quả thật.
Lỗi thường gặp & mẹo
Lỗi 1 — Coi "tích hợp" là một dòng requirement. Mỗi tích hợp tối thiểu là: luồng chính + luồng lỗi + xác thực + đối soát. Đừng bao giờ để nó là một dòng.
Lỗi 2 — Hứa tích hợp khi chưa biết hệ thống kia có API. Rất nhiều phần mềm cũ ở VN (đặc biệt phần mềm nội bộ, ERP đời cũ) không có API mở. "Tích hợp" lúc đó có thể phải làm qua file Excel, hoặc thậm chí không khả thi. Luôn xác nhận sự tồn tại của API trước khi đưa vào scope.
Lỗi 3 — Quên kịch bản lỗi. Dev sẽ luôn hỏi "trường hợp sai thì làm gì". Nếu spec không có, dev tự quyết, và thường quyết theo hướng kỹ thuật chứ không theo trải nghiệm khách hàng.
Lỗi 4 — Nhầm lẫn polling và webhook. Nếu requirement là "real-time", gần như chắc chắn bạn cần webhook, không phải để hệ thống "hỏi liên tục".
Mẹo vàng cho ex-Sales: Bạn đã quen đọc hợp đồng và soi từng điều khoản "nếu bên A không giao hàng đúng hạn thì sao". Hãy dùng đúng phản xạ đó với API spec. API chính là một hợp đồng giữa hai hệ thống, và bảng mã lỗi chính là các điều khoản phạt. Tư duy "đọc kỹ điều khoản trước khi ký" của bạn là siêu năng lực ở đây.
Mẹo thực hành: Cài Postman (miễn phí), xin dev cho bạn một collection API có sẵn, và tự bấm nút "Send" để xem request/response thật. Nửa giờ nghịch Postman dạy bạn nhiều hơn 10 trang lý thuyết.
Bài tập thực hành
Bài 1 — Bóc tách requirement. Cho yêu cầu: "Hệ thống bán vé sự kiện cần tích hợp đăng nhập bằng Google và thanh toán qua VNPay." Hãy liệt kê: có mấy API liên quan? Mỗi API gửi gì, nhận gì? Vẽ chiều mũi tên dữ liệu cho từng cái.
Bài 2 — Viết bảng dữ liệu. Với API "tạo đơn hàng" của một shop online, hãy lập bảng 3 cột (Trường | Bắt buộc/Tùy chọn | Ý nghĩa) cho ít nhất 6 trường dữ liệu.
Bài 3 — Liệt kê kịch bản lỗi. Với tích hợp thanh toán VNPay, liệt kê ít nhất 5 trường hợp lỗi và đề xuất thông báo hiển thị cho người dùng cuối với mỗi lỗi.
Bài 4 — Đọc docs thật. Vào trang tài liệu công khai của VNPay hoặc MoMo, tìm endpoint tạo giao dịch, chụp lại ví dụ request và ghi chú 3 trường dữ liệu bạn thấy quan trọng nhất về mặt nghiệp vụ.
Bài 5 — Phân biệt khái niệm. Giải thích bằng ngôn ngữ của chính bạn (cho một bạn Sales khác chưa biết gì) sự khác nhau giữa: GET và POST; polling và webhook; rate limit và pagination.
Tóm tắt
API không phải là "chuyện của dev" — nó là xương sống của gần như mọi requirement tích hợp mà bạn sẽ gặp với tư cách BA. Bạn không cần biết code, nhưng bạn cần hiểu API như một hợp đồng giao tiếp giữa hai hệ thống: gửi đi cái gì (request), nhận về cái gì (response), khi sai thì xử lý ra sao (mã lỗi), và ai được phép gọi (xác thực).
Hãy nhớ ba điều: (1) mọi cụm từ "tích hợp / đồng bộ / đăng nhập bằng" đều là tín hiệu của một API cần làm rõ; (2) một tích hợp tối thiểu gồm luồng chính, luồng lỗi, xác thực và đối soát — không bao giờ là một dòng; (3) tư duy đọc kỹ điều khoản hợp đồng của dân Sales/BD chính là siêu năng lực để bóc tách API spec. Khi bạn nắm được API literacy ở mức này, buổi grooming với dev sẽ không còn là nơi bạn ngồi nghe, mà là nơi bạn dẫn dắt cuộc thảo luận bằng những câu hỏi đúng.