Cách chốt đặc tả API trước khi hai hệ thống tích hợp

Tích hợp thường chậm không phải vì thiếu endpoint, mà vì hai phía hiểu khác nhau về dữ liệu, lỗi và cách gửi lại yêu cầu. Một đặc tả API đủ rõ giúp product, engineering và QA kiểm tra các điểm này trước khi kết nối hệ thống thật.

03/10/2026 8 phút đọc
Đặc tả API giúp hai hệ thống thống nhất dữ liệu, hành vi và trách nhiệm.
Trên trang này ↓

Một sản phẩm bán hàng cần gửi đơn đã duyệt sang hệ thống vận hành. Backend đã dựng endpoint, nhưng hai đội dùng tên trạng thái khác nhau. Bên gửi thử lại khi quá thời gian chờ, bên nhận lại tạo thêm một đơn mới.

Phần chưa chốt là hành vi giữa hai hệ thống: dữ liệu bắt buộc, kết quả thành công, lỗi có thể thử lại và khóa nhận biết yêu cầu đã xử lý.

Thống nhất timeout, retry và xử lý yêu cầu trùng trước khi tích hợp.
Thống nhất timeout, retry và xử lý yêu cầu trùng trước khi tích hợp.

Mô tả tính năng chưa đủ để bắt đầu tích hợp

Luồng nghiệp vụ giải thích người dùng muốn đạt kết quả gì. Đặc tả API giải thích hai hệ thống trao đổi dữ liệu ra sao. Test case xác nhận hành vi đã chạy đúng hay chưa. Ba phần liên quan nhưng không thay thế nhau.

Một ticket ghi “gửi đơn hàng sang vận hành sau khi sales duyệt” vẫn để lại câu hỏi về trạng thái duyệt, dữ liệu thiếu, cách trả lỗi và nơi người vận hành kiểm tra. Nếu chỉ hỏi khi dev bắt đầu kết nối, mỗi đội sẽ tự điền phần còn thiếu theo cách riêng. Bài cách chuyển ghi chú sản phẩm thành spec và test case giúp làm rõ yêu cầu tính năng. Với tích hợp, đội cần thêm hợp đồng tại ranh giới hệ thống.

Nội dung nào phải có trong đặc tả API?

Tài liệu cần nói rõ sự kiện kích hoạt, chiều dữ liệu, nơi giữ bản ghi chính và kết quả nghiệp vụ. Mỗi trường trong request và response phải có kiểu dữ liệu, điều kiện bắt buộc, giá trị cho phép cùng ý nghĩa. Ví dụ mẫu cần đủ gần dữ liệu thật để QA dùng làm fixture, nhưng phải bỏ thông tin nhạy cảm.

Lỗi nên được chia theo hành động xử lý. Dữ liệu thiếu cần sửa đầu vào, lỗi phụ thuộc tạm thời có thể thử lại, còn lỗi xác thực phải dừng và cảnh báo người phụ trách cấu hình. Một thông báo lỗi chung không cho bên gọi biết bước tiếp theo.

Cách xử lý timeout, retry và yêu cầu trùng

Bên gọi có thể hết thời gian chờ dù bên nhận đã xử lý xong. Nếu gửi lại mà không có khóa định danh ổn định, một đơn hàng có thể được tạo nhiều lần. Đặc tả phải chốt thời gian chờ, số lần thử lại và cách nhận biết cùng một yêu cầu.

Khóa chống trùng nên gắn với hành động nghiệp vụ, không dựa vào thời điểm gửi. Khi nhận lại cùng khóa, hệ thống trả kết quả cũ hoặc trạng thái hiện tại. Nếu nội dung đã thay đổi, API cần từ chối để đội kiểm tra nguồn dữ liệu.

Thay đổi phiên bản phải đi cùng kiểm thử và khả năng tương thích.
Thay đổi phiên bản phải đi cùng kiểm thử và khả năng tương thích.

Quy trình chốt đặc tả trước khi viết phần tích hợp

  1. 1. Chọn một luồng nghiệp vụ cụ thể

    Product mô tả sự kiện bắt đầu, trạng thái đầu vào và kết quả cần có. Các luồng khác mục đích được tách riêng.

  2. 2. Xác định trách nhiệm của từng hệ thống

    Đội chốt bên tạo định danh, nơi giữ dữ liệu chính và người xử lý ngoại lệ.

  3. 3. Viết ví dụ thành công trước

    Engineering tạo request và response mẫu. Product kiểm tra ý nghĩa, QA xác nhận có thể dùng để kiểm thử.

  4. 4. Liệt kê lỗi và hành động tiếp theo

    Đội rà dữ liệu thiếu, trạng thái sai, thiếu quyền và lỗi phụ thuộc. Mỗi lỗi phải chỉ rõ bên xử lý và khả năng thử lại.

  5. 5. Chốt cơ chế gửi lại và thay đổi phiên bản

    Tech lead chốt timeout, retry, khóa chống trùng và cách duy trì khả năng tương thích.

  6. 6. Chuyển đặc tả thành kiểm thử

    QA và engineering dùng ví dụ đã duyệt để tạo contract test, mock hoặc fixture.

Quyền truy cập phải bám theo tác vụ

API tạo đơn không nên mặc nhiên có quyền sửa khách hàng, xóa dữ liệu hoặc đọc toàn bộ lịch sử. Thông tin xác thực chỉ có quyền cần cho luồng đã chốt. Nếu yêu cầu đi qua nhiều dịch vụ, log cần giữ mã tương quan nhưng không ghi dữ liệu nhạy cảm nguyên dạng.

Thay đổi API mà không làm hỏng bên đang sử dụng

Thêm trường tùy chọn thường ít rủi ro hơn đổi tên hoặc xóa trường cũ. Đặc tả cần nêu giá trị mặc định và thời điểm trường trở thành bắt buộc. Với thay đổi không tương thích, đội phải chốt phiên bản mới, thời gian chạy song song và tiêu chí ngừng phiên bản cũ. Đây cũng là một phần của quản lý thay đổi phạm vi MVP, vì chỉnh sửa API có thể làm đổi dữ liệu, test case và mốc bàn giao.

Checklist trước khi hai phía bắt đầu tích hợp

Dữ liệu và hành vi

  • Đã có request và response mẫu cho trường hợp thành công.
  • Trường bắt buộc, trường tùy chọn và giá trị hợp lệ đã rõ.
  • Nguồn dữ liệu chính cùng quy tắc cập nhật đã được xác nhận.
  • Mỗi nhóm lỗi đều chỉ ra hành động tiếp theo.

Kỹ thuật và bàn giao

  • Timeout, retry và khóa chống trùng đã được chốt.
  • Quyền truy cập chỉ bao phủ tác vụ cần thiết.
  • QA có thể dựng test mà không phải hỏi lại yêu cầu.
  • Cách thay đổi phiên bản và thông báo cho bên sử dụng đã rõ.

Tiêu chí hoàn thành phải kiểm tra được từ hai phía

Một yêu cầu mẫu trả kết quả đúng chưa đủ để hoàn thành tích hợp. Hai đội cần kiểm tra dữ liệu sai, lỗi tạm thời, gửi trùng, thiếu quyền và khả năng truy vết. Mỗi kết quả phải quan sát được qua trạng thái hoặc log.

Đọc tiếp

Bài viết liên quan

Xem tất cả bài viết ↗

Chốt phạm vi tích hợp trước khi bắt đầu phát triển

Auranium có thể cùng đội làm rõ luồng nghiệp vụ, đặc tả API, test case và tiêu chí bàn giao cho sản phẩm đang xây.

  • Xác định hệ thống gửi, hệ thống nhận và nguồn dữ liệu chính
  • Chốt hành vi thành công, lỗi, gửi lại và xử lý trùng
  • Chuyển yêu cầu đã duyệt thành test case có thể nghiệm thu
Trao đổi với Auranium
Bắt đầu hành trình của bạn

Nói chuyện với chúng tôi

Chúng tôi sẽ lắng nghe, đặt đúng câu hỏi, và nói thật nếu chúng tôi không phải lựa chọn tốt nhất cho bạn.

Số điện thoại

(+84) 094 4686 093

Zalo

(+84) 094 4686 093

Thời gian làm việc

Mon-Sat (08:00 - 21:00)