Application Programming Interface(API)

Hình dung một quầy giao dịch. Bạn đưa phiếu yêu cầu theo mẫu, nhân viên nhận, xử lý bên trong rồi trả lại kết quả. Bên trong họ làm gì thì bạn không biết, và cũng không cần biết. Việc của bạn là điền đúng mẫu. API là cái quầy đó giữa hai phần mềm — có mẫu phiếu, có kết quả trả về, có cả trường hợp bị từ chối.

BA không cần biết viết API. BA cần đọc được tài liệu API để biết dữ liệu nào lấy được, dữ liệu nào không, và tích hợp này khả thi tới đâu.

Đọc tài liệu API cần nhìn gì

Bỏ qua phần code mẫu bằng Java hay Python. Năm mục dưới đây mới là phần của bạn:

1. Endpoint: địa chỉ của từng chức năng, ví dụ /v1/customers/{id}. Nhìn danh sách endpoint là biết hệ thống kia cho phép làm gì.
2. Method: GET lấy dữ liệu, POST tạo mới, PUT thay thế toàn bộ bản ghi, PATCH chỉ sửa vài trường gửi lên, DELETE xoá. Hai cái ở giữa nhìn giống nhau, hậu quả khác hẳn.
3. Request và response: những trường gửi đi và những trường nhận về, kèm kiểu dữ liệu, bắt buộc hay không.
4. Status code: 200 thành công, 201 đã tạo, 400 dữ liệu gửi sai, 401 chưa xác thực, 403 không có quyền, 404 không tìm thấy, 429 gọi quá nhiều, 500 lỗi phía họ.
5. Authentication: hệ thống kia yêu cầu API key, token OAuth 2.0, hay chứng thư số. Ai cấp, hạn bao lâu, hết hạn thì làm gì.

Thêm hai thứ ít được để ý mà rất hay gây trễ dự án: giới hạn số lần gọi (rate limit) và môi trường sandbox để kiểm thử.

Một cuộc gọi trông như thế nào

POST /v1/orders
Authorization: Bearer eyJhbGciOi...
Content-Type: application/json

{
  "customer_code": "KH00123",
  "items": [
    { "sku": "AO-THUN-M", "qty": 2, "price": 189000 }
  ],
  "note": "Giao gio hanh chinh"
}

Và phía kia trả về:

HTTP/1.1 201 Created

{
  "order_id": "ORD-2026-000871",
  "status": "confirmed",
  "total": 378000,
  "created_at": "2026-03-11T09:42:15+07:00"
}

Đọc được hai khối trên là đủ. Đủ để ngồi họp với đội tích hợp và hỏi những câu đúng chỗ, không cần biết thêm dòng code nào.

Dùng Postman để tự kiểm

Postman là công cụ miễn phí cho phép bạn gọi thử API mà không cần code. Quy trình mình hay làm:

1. Xin đội kỹ thuật một tài khoản môi trường test và một token.
2. Tạo request mới, chọn method, dán URL, thêm header Authorization.
3. Với POST, dán JSON vào tab Body, chọn kiểu raw JSON.
4. Bấm Send, đọc status code và phần response.
5. Thử luôn các trường hợp xấu: thiếu trường bắt buộc, mã khách không tồn tại, token sai. Xem hệ thống trả lỗi ra sao.

Lần đầu làm sẽ lóng ngóng, lần thứ ba thì thành thói quen. Rồi tới lúc khách hỏi giữa cuộc họp, bạn bấm Send xem thử luôn, thay vì hẹn trả lời sau khi dev rảnh.

Mô tả một tích hợp trong tài liệu yêu cầu

Đừng viết chung chung kiểu "hệ thống A tích hợp với hệ thống B". Một mục tích hợp đủ dùng gồm:

• Mục đích nghiệp vụ: đồng bộ khách hàng mới từ CRM sang hệ thống thẻ thành viên.
• Chiều và người khởi xướng: CRM gọi sang, một chiều.
• Thời điểm: ngay khi khách được duyệt, không phải theo lô cuối ngày.
• Bảng mapping trường: tên trường bên A, tên trường bên B, quy tắc chuyển đổi, bắt buộc hay không.
• Xử lý lỗi: gọi thất bại thì thử lại mấy lần, cách nhau bao lâu, quá số lần thì báo cho ai. Kèm luôn khoá chống trùng (idempotency key): mỗi lần đẩy một khách hàng hay một đơn, bên gửi gắn một mã duy nhất và bên nhận cam kết cùng mã đó chỉ tạo đúng một bản ghi. Thiếu dòng này thì lần thử lại sau một cú timeout sẽ đẻ thêm một khách trùng — mà timeout không có nghĩa là bên kia chưa tạo — và không ai biết cho tới lúc chạy báo cáo.
• Đối soát: cuối ngày so số bản ghi hai bên bằng cách nào.

Ví dụ thực tế

11h trưa ngày thứ ba sau khi lên sản xuất, đơn bắt đầu rớt hàng loạt. Test trước đó chạy đẹp, sandbox không kêu một tiếng. Lý do: sàn giao hàng đặt rate limit 60 lần gọi mỗi phút, hệ thống bên mình gửi dồn 412 đơn cùng lúc và không xử lý mã 429. Con số 60 nằm ngay trang hai của tài liệu API. Không ai đọc.

Từ hôm đó, mục đầu tiên mình đọc trong mọi tài liệu API là giới hạn gọi.