← Tài liệu
Phiên bản & ngừng hỗ trợ
Cách API, công cụ AI và webhook thay đổi theo thời gian, và bạn cần làm gì để tích hợp không bị gãy.
Phiên bản REST API
- Phiên bản nằm trong đường dẫn:
/api/v1/…. Mọi đường hiện tại là v1. - Một phiên bản mới (
/api/v2/…) chỉ ra đời khi có thay đổi phá vỡ; v1 vẫn chạy song song trong thời gian chuyển đổi. - OpenAPI tải về (
/openapi.json) luôn là bản đang chạy thật.
Thay đổi không phá vỡ — có thể xảy ra bất cứ lúc nào
- Thêm trường mới vào phản hồi hoặc payload webhook.
- Thêm tham số tuỳ chọn, thêm đường API, công cụ AI hoặc sự kiện webhook mới.
- Thêm giá trị mới vào trường dạng liệt kê (trạng thái, loại…).
- Ứng dụng của bạn phải bỏ qua trường lạ và không giả định thứ tự trường.
Thay đổi phá vỡ — luôn báo trước
- Gỡ hoặc đổi tên trường, đổi kiểu dữ liệu, thêm tham số bắt buộc, gỡ đường API.
- Được báo trước trên Nhật ký thay đổi và qua thư tới chủ ứng dụng đã đăng ký, kèm ngày áp dụng.
- Đường sắp gỡ vẫn trả kết quả bình thường cho tới ngày áp dụng.
Công cụ AI (MCP)
- Danh mục công cụ được sinh trực tiếp từ từng phân hệ; trợ lý AI nên đọc công cụ danh mục (vd
crm_tool_catalog) mỗi session thay vì lưu cứng schema. - Công cụ bị gỡ biến khỏi danh sách và hiện ở mục Gỡ trong Nhật ký thay đổi.
- Công cụ ghi và xuất luôn cần người dùng bấm Xác nhận — quy tắc này không đổi theo phiên bản.
Webhook
- Phong bì sự kiện mang
api_version(hiện làv1); cấu trúc phong bì chỉ đổi khi lên phiên bản mới. - Nội dung
data.objectcó thể được thêm trường; danh sách trường hiện tại có trên trang Webhooks.