Real-world BA case study: order management API — API and Technical Fundamentals cho BA

Mở đầu — vì sao bài này quan trọng

Suốt 56 bài trước, chúng ta đã đi qua gần như toàn bộ "bộ công cụ" kỹ thuật mà một Business Analyst hiện đại cần: REST, JSON, HTTP methods, status codes, authentication, pagination, error design, idempotency, webhooks, rate limiting... Mỗi khái niệm đều quan trọng, nhưng trong thực tế công việc, không ai trả lương cho bạn để liệt kê định nghĩa. Người ta trả lương cho bạn để ghép tất cả những mảnh ghép đó lại thành một đặc tả API thực sự dùng được, giải quyết một bài toán nghiệp vụ cụ thể, làm hài lòng nhiều bên liên quan cùng lúc.

Đó chính là điều bài học này muốn rèn cho bạn. Chúng ta sẽ không học thêm khái niệm mới. Thay vào đó, bạn sẽ ngồi vào ghế của một BA tại một startup thương mại điện tử Việt Nam, nhận một yêu cầu mơ hồ từ ban lãnh đạo ("làm cho tôi cái API quản lý đơn hàng"), rồi đi qua từng bước: phỏng vấn stakeholder, vẽ ra mô hình dữ liệu, định nghĩa endpoint, thiết kế vòng đời đơn hàng, xử lý tích hợp với đối tác giao vận, và bàn giao một spec mà cả lập trình viên lẫn đối tác bên ngoài đều đọc hiểu được.

Order management (quản lý đơn hàng) là "trái tim" của hầu hết hệ thống thương mại điện tử. Nó chạm vào tiền, vào kho, vào khách hàng, vào giao vận — nghĩa là khi nó sai, mọi bộ phận đều la làng. Nếu bạn làm tốt case study này, bạn sẽ tự tin xử lý hầu hết các domain phức tạp khác (đặt phòng, ví điện tử, bảo hiểm...) vì kỹ năng tư duy là giống nhau.

Khái niệm cốt lõi

Trước khi vào case study, hãy thống nhất khung tư duy mà một BA dùng khi spec một API nghiệp vụ. Đây không phải khái niệm kỹ thuật mới, mà là trình tự suy nghĩ.

Bối cảnh đề bài

Công ty giả định: MộcShop, một startup thương mại điện tử bán đồ gia dụng và nội thất nhỏ, trụ sở tại TP.HCM, đang xử lý khoảng 1.200 đơn/ngày và tăng trưởng 15%/tháng. Hiện tại đội vận hành (admin team) quản lý đơn bằng một bảng Google Sheets thủ công và copy-paste mã vận đơn từ web của bên giao hàng. Ban giám đốc muốn xây một Order Management API để: (1) đội admin nội bộ có giao diện quản lý đơn riêng, và (2) tích hợp với 3 đối tác logistics (giả định: GiaoHangNhanh, Ahamove, và một đối tác nội bộ tự giao ở nội thành) để tự động đẩy đơn và nhận cập nhật trạng thái.

Bốn câu hỏi BA phải trả lời

Với bất kỳ API nghiệp vụ nào, bạn phải làm rõ bốn thứ:

Tài nguyên (resources) là gì? — Đây là các danh từ: order, order_item, shipment, customer. Mỗi tài nguyên sẽ thành một nhóm endpoint.
Vòng đời (lifecycle) của tài nguyên chính — Đơn hàng đi qua những trạng thái nào? Ai/cái gì được phép chuyển trạng thái? Đây là phần dễ bị bỏ sót nhất nhưng lại gây nhiều bug nhất.
Ai gọi API, với quyền gì? — Admin nội bộ, hệ thống logistics, hay cả khách hàng? Mỗi nhóm người dùng có nhu cầu và quyền hạn khác nhau.
Sự kiện (events) nào cần thông báo ra ngoài? — Khi đơn chuyển trạng thái, ai cần biết? Đây là nơi webhook xuất hiện.

Stakeholder và "ngôn ngữ" của họ

Một sai lầm kinh điển: BA chỉ nói chuyện với lập trình viên. Trong case study này có ít nhất bốn nhóm stakeholder, và mỗi nhóm "muốn" những thứ khác nhau từ cùng một API:

Đội vận hành/admin: muốn lọc, tìm, đổi trạng thái đơn nhanh; muốn biết đơn nào đang kẹt.
Đội tài chính/kế toán: quan tâm tổng tiền, trạng thái thanh toán, hoàn tiền — họ cần dữ liệu bất biến để đối soát.
Đối tác logistics: cần nhận đơn theo định dạng họ hiểu, và đẩy ngược trạng thái giao hàng về.
Đội kỹ thuật: muốn spec rõ ràng, không mơ hồ, có status code và error format chuẩn để code.

Nhiệm vụ của BA là dịch nhu cầu nghiệp vụ của bốn nhóm này thành một bản đặc tả kỹ thuật thống nhất.

Tình huống thực tế

Tình huống 1 — Cuộc họp khai thác yêu cầu và "trạng thái ẩn"

BA của MộcShop (gọi là chị Lan) ngồi với trưởng nhóm vận hành. Yêu cầu ban đầu chỉ là: "Cho tôi xem danh sách đơn và cho đổi trạng thái." Nghe thì đơn giản. Nhưng chị Lan hỏi sâu: "Một đơn hàng trải qua những bước nào từ lúc khách đặt đến lúc nhận hàng?"

Trưởng nhóm liệt kê: đặt hàng → xác nhận → đóng gói → giao cho shipper → giao thành công. Chị Lan hỏi tiếp: "Thế đơn bị hủy thì sao? Khách bom hàng (giao thất bại) thì đơn về đâu? Đơn đã thanh toán online mà hủy thì có cần hoàn tiền không?" Lúc này lộ ra hàng loạt trạng thái ẩn mà không ai nói ra ban đầu: cancelled, delivery_failed, returned, refunded.

Kết quả, chị Lan vẽ ra một sơ đồ chuyển trạng thái (state machine) đầy đủ:

pending → confirmed → packed → shipping → delivered
   │          │                    │
   └──────────┴──> cancelled       └──> delivery_failed → returned → refunded

Quy tắc kèm theo: không được chuyển ngược (đơn delivered không quay lại packed); chỉ đơn pending hoặc confirmed mới hủy được; đơn đã shipping muốn dừng phải đi qua delivery_failed.

Bài học: Phần lớn rủi ro của API quản lý đơn không nằm ở việc "lấy danh sách đơn", mà nằm ở các đường chuyển trạng thái hợp lệ. BA giỏi là người moi ra những nhánh mà nghiệp vụ "quên nói". Đây là endpoint quan trọng nhất: thay vì một PATCH /orders/{id} cho phép sửa bừa trạng thái, chị Lan thiết kế các action endpoint rõ nghĩa như POST /orders/{id}/cancel, POST /orders/{id}/confirm — mỗi endpoint kiểm tra trạng thái nguồn hợp lệ và trả 409 Conflict nếu chuyển sai luồng.

Tình huống 2 — Tích hợp logistics và bài toán webhook đẩy trạng thái

MộcShop tích hợp với GiaoHangNhanh (GHN). Luồng nghiệp vụ: khi đơn chuyển sang packed, hệ thống MộcShop gọi API của GHN để tạo vận đơn, nhận về một mã tracking_code. Sau đó, GHN sẽ cập nhật trạng thái giao hàng (đang lấy hàng, đang giao, giao thành công...) — và đây là điểm mấu chốt: làm sao MộcShop biết được khi GHN cập nhật?

Chị Lan cân nhắc hai phương án (kiến thức từ bài 26): polling (cứ vài phút lại hỏi GHN "đơn này tới đâu rồi?") hay webhook (GHN chủ động gọi về MộcShop khi có thay đổi). Với 1.200 đơn/ngày và đang tăng, polling sẽ tốn tài nguyên và bị trễ. Chị Lan chọn webhook: thiết kế một endpoint nhận sự kiện POST /webhooks/logistics/ghn mà GHN sẽ gọi.

Nhưng GHN, Ahamove và đối tác nội bộ mỗi bên có định dạng payload khác nhau và bộ trạng thái khác nhau. GHN trả "status": "delivered", Ahamove trả "order_status": "COMPLETED", đối tác nội bộ trả "state": 5. Chị Lan đặc tả một bảng ánh xạ trạng thái (mapping table) trong spec: mỗi trạng thái của từng đối tác được map về một trạng thái chuẩn nội bộ. Lập trình viên chỉ cần viết một lớp adapter theo bảng này.

Một con số thực tế: trong tháng đầu chạy thử, có khoảng 3% webhook bị trùng lặp (GHN gửi lại do timeout phía họ). Nếu xử lý ngây thơ, một sự kiện "giao thành công" gửi hai lần có thể kích hoạt hai lần cộng doanh thu. Chị Lan áp dụng kiến thức về idempotency (bài 25): mỗi webhook mang một event_id, hệ thống lưu lại các event_id đã xử lý và bỏ qua bản trùng.

Bài học: Khi tích hợp nhiều đối tác bên thứ ba, công việc lớn nhất của BA không phải định nghĩa endpoint của mình, mà là chuẩn hóa sự khác biệt giữa các đối tác thành một mô hình thống nhất — và lường trước những "rắc rối thực tế" như trùng lặp, timeout, sai lệch trạng thái.

Tình huống 3 — Quyền truy cập và dữ liệu nhạy cảm

Một tình huống suýt gây sự cố tại MộcShop: đối tác Ahamove cần gọi API để lấy thông tin đơn cần giao. Bản spec đầu tiên dùng chung endpoint GET /orders/{id} cho cả admin nội bộ lẫn đối tác. Vấn đề: response chứa cả cost_price (giá vốn), internal_note, và số điện thoại đầy đủ của khách. Không có lý do gì đối tác giao vận cần biết giá vốn của MộcShop.

Chị Lan tách bạch: đối tác dùng API key riêng (bài 16, 19), và endpoint dành cho đối tác chỉ trả về tập trường tối thiểu cần cho việc giao hàng — tên người nhận, địa chỉ, số điện thoại (có thể che một phần), khối lượng, ghi chú giao hàng. Còn cost_price và internal_note chỉ xuất hiện với token của admin.

Bài học: Cùng một tài nguyên order nhưng hình dạng dữ liệu trả ra phải khác nhau tùy người gọi. BA phải nghĩ về bảo mật dữ liệu (liên quan bài 50 — OWASP API Top 10, lỗi "Excessive Data Exposure") ngay từ khâu spec, chứ không để đến lúc lộ dữ liệu mới sửa.

Hướng dẫn từng bước

Đây là quy trình bạn có thể áp dụng cho bất kỳ case study API nghiệp vụ nào, minh họa bằng order management.

Bước 1 — Liệt kê tài nguyên và quan hệ. Từ phỏng vấn, rút ra các danh từ chính và quan hệ giữa chúng (kiến thức bài 31): một order có nhiều order_item (1:N); một order thuộc về một customer (N:1); một order có một hoặc nhiều shipment khi tách kiện (1:N). Vẽ sơ đồ quan hệ này ra giấy trước khi đụng vào endpoint.

Bước 2 — Vẽ state machine của tài nguyên trung tâm. Như tình huống 1: liệt kê mọi trạng thái, mọi đường chuyển hợp lệ, và điều kiện kèm theo. Đây là tài liệu mà cả dev lẫn QA sẽ tham chiếu nhiều nhất.

Bước 3 — Thiết kế endpoint theo nhóm hành động. Chia làm ba loại:

Truy vấn: GET /orders (có filter, sort, pagination — bài 22, 23), GET /orders/{id}.
Tạo/sửa: POST /orders, PATCH /orders/{id} (chỉ cho sửa trường an toàn như ghi chú, địa chỉ khi đơn còn pending).
Chuyển trạng thái: action endpoint POST /orders/{id}/confirm, /cancel, /ship... thay vì để client tự set trạng thái tùy tiện.

Bước 4 — Đặc tả request/response cụ thể. Với mỗi endpoint, viết rõ: tham số, body mẫu (JSON), response thành công kèm status code (201 cho tạo mới, 200 cho truy vấn, 409 cho chuyển trạng thái sai), và error format thống nhất (bài 24). Ví dụ lỗi hủy đơn đã giao:

{
  "error": {
    "code": "INVALID_STATE_TRANSITION",
    "message": "Đơn hàng đã giao không thể hủy",
    "current_state": "delivered"
  }
}

Bước 5 — Đặc tả tích hợp ngoài và sự kiện. Định nghĩa các webhook gửi đi (khi đơn đổi trạng thái, thông báo cho hệ thống kế toán) và webhook nhận về (từ logistics). Kèm bảng mapping trạng thái cho từng đối tác. Ghi rõ cơ chế idempotency và retry.

Bước 6 — Rà soát với từng stakeholder. Đưa spec cho đội vận hành ("đủ filter chưa?"), kế toán ("trường tiền có đủ để đối soát?"), đối tác logistics ("payload này bên bạn nhận được không?"), và dev ("có chỗ nào mơ hồ không?"). Đây là bước biến spec từ "đúng trên giấy" thành "dùng được thật".

Lỗi thường gặp & mẹo

Cho phép sửa trạng thái tự do bằng PATCH. Nếu spec để PATCH /orders/{id} nhận luôn {"status": "delivered"}, dev sẽ implement đúng vậy, và rồi ai đó vô tình chuyển một đơn từ pending thẳng lên refunded. Luôn dùng action endpoint có kiểm soát luồng.

Quên trạng thái thanh toán là một trục riêng. Trạng thái giao hàng (shipping, delivered) và trạng thái thanh toán (unpaid, paid, refunded) là hai chiều độc lập. Một đơn có thể delivered nhưng unpaid (COD chưa thu được tiền). Đừng nhồi tất cả vào một trường status.

Bỏ qua trường hợp hủy một phần. Khách đặt 3 món, muốn hủy 1 món. Nếu mô hình chỉ cho hủy nguyên đơn, nghiệp vụ sẽ kẹt. Hỏi sớm: "Hủy/hoàn ở cấp đơn hay cấp item?"

Để mỗi đối tác logistics tự định nghĩa trạng thái rò rỉ vào hệ thống chính. Luôn có một tầng chuẩn hóa. Trạng thái nội bộ của MộcShop không nên xuất hiện chữ "COMPLETED" của Ahamove.

Mẹo — viết "câu chuyện đi qua hệ thống" (happy path + 2 unhappy path). Trước khi nộp spec, tự kể: "Đơn #1234 được tạo, xác nhận, đóng gói, đẩy sang GHN, giao thành công" — và hai kịch bản hỏng: "khách bom hàng" + "đơn online hủy giữa chừng". Nếu spec của bạn trả lời được cả ba câu chuyện này một cách rõ ràng, nó đã đủ vững.

Mẹo — gắn mỗi yêu cầu nghiệp vụ với một stakeholder. Nếu một trường dữ liệu hay endpoint không thuộc về stakeholder nào, hãy nghi ngờ nó là gold-plating (làm thừa).

Bài tập thực hành

Vẽ lại state machine cho đơn hàng MộcShop nhưng tách riêng hai trục: trạng thái giao hàng và trạng thái thanh toán. Liệt kê các đường chuyển hợp lệ trên mỗi trục.

Thiết kế endpoint truy vấn GET /orders cho đội vận hành: cần lọc theo trạng thái, theo đối tác giao hàng, theo khoảng ngày; sắp xếp theo ngày tạo; phân trang. Viết ra URL mẫu đầy đủ với query string (vận dụng bài 8, 22, 23).

Đặc tả một webhook nhận về từ một đối tác giao vận giả định "ZipExpress" trả payload {"shipment_id": "...", "code": "DLV_OK", "ts": 1699999999}. Viết bảng mapping trạng thái của ZipExpress về trạng thái nội bộ, và mô tả cách bạn xử lý webhook trùng lặp.

Tình huống tranh luận: Đội kế toán muốn API trả về cost_price để tính lãi gộp ngay trên màn hình đơn. Đội bảo mật phản đối vì lo lộ giá vốn. Bạn là BA — đề xuất một giải pháp spec dung hòa (gợi ý: phân quyền theo vai trò, hoặc endpoint riêng cho báo cáo).

Viết error response cho ba tình huống: hủy đơn đã giao, xác nhận một đơn không tồn tại, và webhook gửi event_id đã xử lý. Đảm bảo dùng đúng status code và format lỗi thống nhất.

Tóm tắt

Bài này không thêm khái niệm kỹ thuật mới — nó dạy bạn cách ghép mọi thứ đã học thành một bản đặc tả API nghiệp vụ hoàn chỉnh, qua case study order management của startup MộcShop. Những điểm cốt lõi cần khắc ghi:

Trái tim của API quản lý đơn không phải là "lấy danh sách đơn", mà là vòng đời và các đường chuyển trạng thái hợp lệ. Hãy moi cho ra các trạng thái ẩn mà nghiệp vụ quên nói.
Tách bạch các trục dữ liệu độc lập (giao hàng vs thanh toán), và dùng action endpoint thay vì cho sửa trạng thái tự do.
Khi tích hợp nhiều đối tác bên thứ ba, công việc lớn nhất là chuẩn hóa sự khác biệt thành một mô hình thống nhất, và lường trước trùng lặp/timeout bằng idempotency và webhook.
Hình dạng dữ liệu trả ra phải khác nhau tùy người gọi — đừng để giá vốn lọt ra ngoài đối tác giao vận.
Một spec tốt là spec trả lời được cả happy path lẫn các nhánh hỏng, và mỗi yêu cầu đều truy ngược được về một stakeholder cụ thể.

Khi bạn làm chủ được tư duy này, bạn không còn chỉ là người "viết tài liệu" — bạn là người định hình cách cả hệ thống vận hành. Đó chính là giá trị thật sự của một BA kỹ thuật.