Mở đầu — vì sao bài này quan trọng
Nếu bạn từng làm Finance hoặc Kế toán, gần như chắc chắn bạn đã từng "trao đổi dữ liệu" với một hệ thống khác mà không hề gọi nó bằng cái tên kỹ thuật. Bạn tải file sao kê từ ngân hàng về dưới dạng CSV. Bạn xuất file bút toán từ phần mềm kế toán ra Excel rồi import vào hệ thống thuế. Bạn nhận file đối soát từ cổng thanh toán mỗi sáng để khớp với sổ quỹ. Tất cả những hành động đó, về bản chất, đều là tích hợp hệ thống — chỉ là theo cách thủ công, theo lô (batch), và thường trễ một ngày.
Khi chuyển sang vai trò Business Analyst (BA), bạn sẽ liên tục ngồi trong các cuộc họp mà ở đó dev nói: "Cái này mình gọi API của bên đối tác", "Endpoint này trả về 200 hay 401?", "Webhook chưa fire nên trạng thái chưa cập nhật". Nếu bạn gật gù mà không hiểu, bạn sẽ viết requirement sai, ước lượng sai, và mất uy tín với team kỹ thuật. Ngược lại — và đây là tin vui — nền tảng Finance cho bạn một lợi thế mà dân BA xuất thân marketing hay nhân sự không có: bạn đã quá hiểu bản chất nghiệp vụ của việc trao đổi dữ liệu giữa hai bên: đối soát, idempotency (chống trùng), reconciliation, audit trail. API chỉ là cái vỏ kỹ thuật bọc quanh đúng những khái niệm bạn đã thành thạo.
Bài này không biến bạn thành lập trình viên. Mục tiêu là giúp bạn đọc hiểu, mô tả và đặt câu hỏi đúng về API integration ở mức một BA giỏi cần — đủ để viết requirement tích hợp, vẽ luồng dữ liệu, và đối thoại ngang hàng với dev.
Khái niệm cốt lõi
Từ "file batch" sang "API real-time"
Hãy bắt đầu từ thứ bạn đã biết. Trong Finance, hai hệ thống nói chuyện với nhau qua file: một bên ghi file (CSV, XML, fixed-width text), đặt lên server SFTP, bên kia tải về và xử lý. Đặc điểm: theo lô, định kỳ (cuối ngày, cuối tháng), và có độ trễ.
API (Application Programming Interface) là phiên bản real-time, từng giao dịch một của đúng cơ chế đó. Thay vì gom 10.000 giao dịch vào một file rồi gửi lúc nửa đêm, hệ thống A "hỏi" hệ thống B ngay lập tức cho từng giao dịch và nhận câu trả lời trong vài trăm mili-giây.
Một phép so sánh dễ nhớ cho dân Finance: API giống như gọi điện cho ngân hàng để hỏi số dư ngay lúc này, còn file batch giống như chờ sao kê cuối tháng gửi về. Cùng một thông tin, khác nhau ở độ tức thời và độ chi tiết.
REST API — cấu trúc một "yêu cầu"
Phần lớn API hiện đại theo kiểu REST. Bạn không cần thuộc lý thuyết, chỉ cần nắm bốn thành phần của một lời gọi (request):
1. Method (động từ) — bạn muốn làm gì:
GET— lấy dữ liệu về (như xem số dư). Không thay đổi gì cả.POST— tạo mới (như tạo một giao dịch chuyển tiền).PUT/PATCH— cập nhật (như sửa thông tin khách hàng).DELETE— xóa.
GET giống "read-only / chỉ tra cứu", còn POST giống "ghi một bút toán". Một cái không để lại dấu vết thay đổi, một cái thì có.2. Endpoint (địa chỉ) — bạn gọi tới đâu: ví dụ https://api.vietcombank.vn/v1/accounts/12345/balance. Đọc như một đường dẫn thư mục: "trong tài nguyên accounts, lấy tài khoản 12345, mục balance".
3. Headers (thông tin kèm theo): thường chứa xác thực (token, API key) và định dạng dữ liệu. Đây là phần "chứng minh bạn là ai và có quyền không".
4. Body (nội dung): dữ liệu gửi đi, thường ở định dạng JSON. JSON với người Finance không lạ — nó chính là bảng key–value, giống một dòng trong Excel nhưng viết dọc:
{
"tai_khoan_nguon": "0123456789",
"tai_khoan_dich": "9876543210",
"so_tien": 5000000,
"loai_tien": "VND",
"noi_dung": "Thanh toan hoa don T6"
}
Response và Status Code — "câu trả lời" của hệ thống
Sau khi gửi request, hệ thống B trả về response, gồm dữ liệu (JSON) và một con số quan trọng gọi là HTTP status code. Dân Finance nên thuộc nhóm này như thuộc mã lỗi ngân hàng:
- 2xx (200, 201) — Thành công. Giao dịch được nhận, được xử lý.
- 4xx — Lỗi do bên gửi.
400dữ liệu sai định dạng,401chưa xác thực (sai token),403không có quyền,404không tìm thấy,409xung đột (ví dụ giao dịch trùng). - 5xx — Lỗi do bên nhận. Server đối tác đang hỏng, không phải lỗi của bạn.
Webhook — "API gọi ngược"
Có hai cách lấy dữ liệu mới. Cách thứ nhất, polling: bạn cứ vài phút lại GET hỏi "có gì mới không?" — giống nhân viên cứ chốc chốc lại F5 trang sao kê. Tốn kém và trễ. Cách thứ hai, webhook: bạn đăng ký một địa chỉ, khi có sự kiện (ví dụ "khách đã thanh toán thành công"), hệ thống đối tác chủ động gọi tới bạn để báo. Webhook là nền tảng của mọi luồng thanh toán online ở Việt Nam — đây là cách MoMo, VNPay, ZaloPay báo cho website biết đơn hàng đã được trả tiền.
Idempotency và đối soát — nơi BA ex-Finance tỏa sáng
Đây là khái niệm mà bạn hiểu sâu hơn cả nhiều dev junior. Idempotency nghĩa là: gửi cùng một request nhiều lần thì kết quả chỉ xảy ra một lần. Tại sao quan trọng? Vì mạng có thể lỗi: bạn gửi lệnh chuyển 5 triệu, server xử lý xong nhưng phản hồi bị rớt giữa đường, hệ thống bạn tưởng thất bại nên gửi lại — và khách bị trừ tiền hai lần.
Người Finance hiểu ngay rủi ro này vì nó chính là bút toán trùng. Giải pháp kỹ thuật là gắn mỗi giao dịch một Idempotency-Key duy nhất; server thấy key đã xử lý thì trả về kết quả cũ thay vì tạo giao dịch mới. Và sau cùng, dù real-time đến đâu, mọi tích hợp tài chính nghiêm túc vẫn cần một luồng đối soát (reconciliation) cuối ngày — đúng cái nghề bạn đã làm.
Tình huống thực tế
Ví dụ 1 — Tích hợp cổng thanh toán cho sàn TMĐT (bối cảnh giả định hợp lý)
Một sàn thương mại điện tử quy mô vừa ở TP.HCM, tạm gọi là "ChợViệt", cần tích hợp VNPay để khách thanh toán đơn hàng. Bạn — BA xuất thân kế toán — được giao viết requirement.
Luồng kỹ thuật: khi khách bấm "Thanh toán", hệ thống ChợViệt gọi POST tới API tạo phiên thanh toán của VNPay, nhận về một URL, chuyển khách sang trang VNPay. Khách trả tiền xong, VNPay gọi webhook (IPN — Instant Payment Notification) về ChợViệt báo "đơn 1052 đã thanh toán 1.200.000đ thành công". Hệ thống cập nhật đơn sang "Đã thanh toán".
Nhờ nền Finance, bạn lập tức đặt những câu hỏi mà BA thường chỉ học sau vài lần "cháy": Nếu webhook báo thành công nhưng mạng rớt, ChợViệt không nhận được thì sao? Có cơ chế VNPay gửi lại không? Nếu webhook tới hai lần cho cùng đơn 1052, hệ thống có cập nhật trạng thái hai lần và ghi nhận doanh thu gấp đôi không? Cuối ngày có file đối soát để khớp tổng tiền VNPay đã thu với tổng đơn ChợViệt ghi nhận không?
Bài học: chính tư duy đối soát và chống trùng của kế toán giúp bạn viết requirement đầy đủ phần "xử lý lỗi và đối soát" — phần mà sản phẩm hay quên và gây thất thoát tiền thật.
Ví dụ 2 — Fintech đồng bộ giao dịch ngân hàng qua Open API (bối cảnh Việt Nam)
Một startup fintech quản lý chi tiêu, gọi là "Sổ Thông Minh", muốn người dùng kết nối tài khoản ngân hàng để tự động kéo lịch sử giao dịch — thay vì nhập tay. Họ tích hợp Open Banking API của các ngân hàng như VPBank, TPBank qua một nhà cung cấp trung gian.
Trước đây người dùng phải tải file sao kê CSV rồi import. Giờ thì hệ thống GET định kỳ danh sách giao dịch mới. Là BA, bạn nhận ra ngay sự tương đồng: response API trả về danh sách giao dịch có y hệt các cột của một file sao kê — ngày, số tiền, nội dung, mã giao dịch (transaction_id). Bạn viết requirement dùng transaction_id làm khóa chống trùng: nếu giao dịch đó đã có trong database thì bỏ qua, không tạo bản ghi mới. Đây chính xác là logic "khớp mã chứng từ" trong kế toán.
Một con số thực tế đáng lưu ý khi viết requirement: API ngân hàng thường có rate limit (giới hạn số lần gọi), ví dụ tối đa 100 request/phút. Nếu Sổ Thông Minh có 50.000 người dùng và cứ 5 phút đồng bộ một lần, bạn phải tính toán và xếp hàng (queue) các lời gọi, nếu không sẽ bị ngân hàng chặn (429 Too Many Requests).
Bài học: kinh nghiệm đọc sao kê giúp bạn ánh xạ cấu trúc dữ liệu API sang nghiệp vụ ngay lập tức, và đặt ra ràng buộc khử trùng chuẩn xác.
Ví dụ 3 — Tích hợp API hóa đơn điện tử với cơ quan thuế (bối cảnh Việt Nam)
Một doanh nghiệp bán lẻ chuỗi cửa hàng cần tích hợp hệ thống POS với nhà cung cấp hóa đơn điện tử (như VNPT, Viettel) để mỗi giao dịch bán hàng tự phát hành hóa đơn theo quy định Nghị định 123 và truyền dữ liệu lên Tổng cục Thuế.
Mỗi lần bán, POS gọi POST tới API của nhà cung cấp hóa đơn với thông tin đơn hàng; API trả về mã hóa đơn và mã của cơ quan thuế. Ở đây, tính chất không được phép sai và không được trùng là tuyệt đối — phát hành trùng hóa đơn là vi phạm pháp luật thuế. BA ex-Finance hiểu rất rõ độ nghiêm trọng này, nên sẽ nhấn mạnh trong requirement: cơ chế idempotency bắt buộc, lưu đầy đủ request/response để audit, và quy trình xử lý khi API thuế trả về 5xx (server thuế quá tải giờ cao điểm cuối ngày) — phải xếp hàng gửi lại chứ không được bỏ giao dịch.
Bài học: hiểu biết về compliance và audit trail của Finance khiến bạn viết được requirement tích hợp ở mức "chịu được kiểm toán" — điều mà BA thuần kỹ thuật dễ xem nhẹ.
Hướng dẫn từng bước
Khi bạn được giao một yêu cầu tích hợp API với vai trò BA, hãy theo trình tự sau:
Bước 1 — Xác định hướng dữ liệu. Hệ thống của mình gọi đi hay bị gọi đến? Đẩy dữ liệu ra (push) hay kéo dữ liệu về (pull)? Đây là điều đầu tiên cần vẽ rõ trên sơ đồ luồng.
Bước 2 — Đọc tài liệu API (API documentation). Mọi API tốt đều có tài liệu. Bạn không cần đọc hết, chỉ cần tìm: các endpoint liên quan, method, các trường bắt buộc trong body, cách xác thực, và bảng status code. Công cụ như Postman hoặc Swagger UI cho phép bạn bấm thử API mà không cần code — rất nên học để tự kiểm chứng.
Bước 3 — Lập danh mục trường dữ liệu (data mapping). Lập bảng đối chiếu: trường nào của hệ thống mình ↔ trường nào trong request/response API. Đây là kỹ năng bạn đã làm khi map cột Excel sang trường phần mềm kế toán.
Bước 4 — Liệt kê đầy đủ các kịch bản, đặc biệt là kịch bản lỗi. Không chỉ "happy path" (thành công). Hỏi: lỗi 4xx xử lý sao? Lỗi 5xx retry mấy lần? Timeout (không phản hồi) coi là thành công hay thất bại? Trùng request thì sao?
Bước 5 — Định nghĩa cơ chế đối soát. Có file/báo cáo đối soát cuối ngày không? Ai chịu trách nhiệm khi số liệu lệch? Đây là phần bạn nên chủ động thêm vào nhờ kinh nghiệm Finance.
Bước 6 — Viết acceptance criteria và sơ đồ. Diễn đạt mọi kịch bản trên thành tiêu chí nghiệm thu rõ ràng và một sequence diagram (sơ đồ trình tự) thể hiện ai gọi ai, theo thứ tự nào.
Lỗi thường gặp & mẹo
Lỗi 1 — Chỉ mô tả luồng thành công. Đây là lỗi phổ biến nhất của BA mới. Trong tích hợp, phần khó và đắt giá nhất luôn là xử lý lỗi và trường hợp biên. Mẹo: với mỗi lời gọi API, luôn tự hỏi "nếu cái này thất bại thì sao?".
Lỗi 2 — Quên idempotency. Cho rằng "request gửi một lần là một lần". Mạng không hoàn hảo; retry là chuyện thường. Luôn yêu cầu khóa chống trùng cho mọi giao dịch tài chính.
Lỗi 3 — Nhầm webhook là tức thời và đảm bảo 100%. Webhook có thể tới trễ, tới trùng, hoặc không tới. Mẹo: luôn thiết kế thêm cơ chế đối soát/polling dự phòng, đừng phụ thuộc duy nhất vào webhook cho dữ liệu tiền bạc.
Lỗi 4 — Bỏ qua rate limit và phân trang (pagination). API thường chỉ trả về 50–100 bản ghi mỗi lần và giới hạn số lần gọi. Nếu bỏ quên, hệ thống sẽ lấy thiếu dữ liệu hoặc bị chặn.
Mẹo vàng: tận dụng đúng vốn liếng Finance của bạn. Khi cả phòng họp bàn về API, bạn hãy là người đặt câu hỏi về đối soát, chống trùng, và audit. Đó là vùng bạn mạnh hơn người khác, và đó cũng là vùng dự án hay thất bại nhất.
Bài tập thực hành
Bài 1 — Đọc và dịch một response. Lên trang tài liệu công khai của một cổng thanh toán Việt Nam (VNPay hoặc MoMo có sandbox doc). Tìm phần "IPN/Webhook" và liệt kê: webhook gửi method gì, body chứa những trường nào, status code nào báo thành công. Dịch mỗi trường sang nghiệp vụ kế toán tương ứng.
Bài 2 — Viết kịch bản lỗi. Với tình huống ChợViệt ở Ví dụ 1, viết ra ít nhất 5 kịch bản lỗi (webhook trùng, webhook không tới, số tiền webhook khác số tiền đơn hàng, lỗi 5xx khi tạo phiên, khách đóng trình duyệt giữa chừng) và cách hệ thống nên xử lý từng cái.
Bài 3 — Vẽ sequence diagram. Dùng giấy hoặc draw.io, vẽ sơ đồ trình tự cho luồng thanh toán: Khách → ChợViệt → VNPay → webhook → cập nhật đơn → đối soát cuối ngày. Đánh dấu rõ chỗ nào cần idempotency key.
Bài 4 — Thử Postman. Tải Postman (miễn phí), gọi một API công khai đơn giản (ví dụ một API tỷ giá hối đoái). Quan sát request, response và status code thật. Mục tiêu là chạm tay vào API thật một lần.
Tóm tắt
API integration nghe có vẻ thuần kỹ thuật, nhưng với người xuất thân Finance, nó chỉ là phiên bản real-time của đúng việc bạn đã làm: trao đổi dữ liệu giữa hai hệ thống một cách có kiểm soát. Bạn đã nắm bốn thành phần của một REST request (method, endpoint, headers, body), biết đọc status code để phân biệt lỗi 4xx (do mình) và 5xx (do đối tác), hiểu webhook là "API gọi ngược" nền tảng của thanh toán online Việt Nam, và quan trọng nhất — bạn thấy idempotency với đối soát chính là tư duy chống trùng và reconciliation quen thuộc.
Lợi thế cạnh tranh của bạn không nằm ở việc code, mà ở việc đặt đúng câu hỏi về xử lý lỗi, chống trùng và audit — những điểm mù mà nhiều BA bỏ qua nhưng lại là nơi dự án tài chính dễ "cháy" nhất. Hãy là người mang tư duy kiểm soát rủi ro vào bàn họp kỹ thuật. Bài tiếp theo về Jira và Confluence sẽ giúp bạn ghi lại và quản lý chính những requirement tích hợp này một cách chuyên nghiệp.