Một lần kết nối chạy ổn hôm qua có thể sai hôm nay dù endpoint vẫn trả 200. Giá từ số chuyển sang chuỗi, trường ngày mất timezone hoặc mã trạng thái có giá trị mới đều có thể khiến hệ thống đích hiểu nhầm. Khi API đổi kiểu dữ liệu, sửa một dòng mapping trước khi biết tác động thường chỉ chuyển lỗi sang bước sau.
Đừng gom mọi thay đổi thành “đổi schema”
Cần tách cấu trúc khỏi ý nghĩa. Trường amount vẫn là số nhưng đổi từ đồng sang đơn vị nhỏ hơn là thay đổi nghiệp vụ. Trường status vẫn là chuỗi nhưng thêm giá trị chưa được xử lý có thể làm rơi đơn hàng vào nhánh mặc định. Việc parser không lỗi chưa chứng minh consumer xử lý đúng.
| Thay đổi giả định | Rủi ro | Cách chặn |
|---|---|---|
| amount: 1200 thành “1200” | So sánh hoặc tính toán sai kiểu | Kiểm kiểu, chỉ chuyển đổi theo quy ước được duyệt |
| Không có due_date | Không biết nguồn thiếu hay không áp dụng | Quy định trường bắt buộc và nhánh chờ xác nhận |
| due_date: null | Bị thay bằng ngày hôm nay ngoài ý muốn | Giữ trạng thái chưa có giá trị nếu hợp đồng cho phép |
| currency có mã mới | Tính tổng tiền khác đơn vị | Tách theo tiền tệ, không tự quy đổi |
Bảng hợp đồng trường cần cả người sử dụng
Ghi tên trường, đường dẫn trong payload, kiểu, bắt buộc hay tùy chọn, khả năng nhận null, đơn vị, danh sách giá trị, consumer đang dùng và hành động khi không hợp lệ. Thêm người có quyền duyệt ý nghĩa nghiệp vụ, không chỉ người sửa connector. Một trường “không dùng” ở màn hình có thể vẫn được dùng trong báo cáo hoặc quy tắc gửi email.
Trong OpenAPI 3.0.4, required và nullable giải quyết hai câu hỏi khác nhau: thuộc tính có phải xuất hiện không, và có được nhận giá trị null không. Cần kiểm đúng phiên bản OpenAPI; cú pháp nullable của 3.0 không phải quy tắc chung để sao chép sang mọi phiên bản hoặc mọi validator.
Ví dụ giả định: hạn thanh toán bị đổi định dạng
Nguồn trước gửi ngày 2026-10-20, sau gửi thời điểm có offset. Nhóm tích hợp không nên cắt chuỗi về ngày mà chưa hỏi hạn được tính theo múi giờ nào. Lưu mẫu cũ và mới đã khử dữ liệu cá nhân, hỏi chủ nghiệp vụ cách xử lý và ghi phiên bản mapping. Nếu chưa có câu trả lời, đưa bản ghi vào hàng chờ thay vì tự suy diễn.
Chạy các mẫu hợp lệ, thiếu trường, null, sai kiểu và giá trị enum chưa biết qua consumer thực sự chịu tác động. Một endpoint mô tả đúng schema không tự chứng minh mọi consumer đã tương thích; cần bằng chứng từ từng đường xử lý có liên quan.
Điều kiện để phát hành mapping mới
- Đã xác định consumer và phần dữ liệu bị ảnh hưởng.
- Có mẫu trước/sau và quyết định nghiệp vụ được duyệt.
- Có ca kiểm tra cho thiếu, null, sai kiểu và giá trị mới.
- Lưu phiên bản mapping, cách rollback và bản ghi chờ xử lý.
- Không âm thầm ép giá trị lỗi thành 0 hoặc chuỗi rỗng.
Kiểm tra schema không phát hiện hết thay đổi ý nghĩa. Vì vậy bảng đơn vị và quyết định nghiệp vụ vẫn cần review thủ công, nhất là dữ liệu tiền hoặc quyền truy cập.
Chuẩn bị yêu cầu sửa kết nối
Gửi mẫu đã che thông tin nhạy cảm cùng bảng consumer khi trao đổi yêu cầu gia công phần mềm. Nếu thay đổi xuất hiện ở đầu vào CSV, dùng thêm bảng kiểm CSV trước khi import; kiểm cấu trúc API không thay thế việc duyệt thay đổi dữ liệu hàng loạt.
Nguồn tham khảo và giới hạn
Tài liệu chính thức 1. Quy trình, bảng và ví dụ trong bài là đề xuất nghiệm thu; ví dụ giả định không phải dự án hoặc kết quả khách hàng của Onter. Phạm vi triển khai cần xác nhận theo hệ thống hiện hữu.
