📌 HƯỚNG DẪN GỌI API THÔNG BÁO ĐỒNG BỘ DỮ LIỆU

1. Mục đích

API này dùng để thông báo cho hệ thống dữ liệu đã thay đổi, cần đồng bộ.

Lưu ý quan trọng: Để đảm bảo tính chính xác trong quá trình đồng bộ, các bản ghi dữ liệu bắt buộc phải bao gồm trường MA_KY. Nếu không có trường MA_KY, dữ liệu sẽ không được đồng bộ.

2. Thông tin endpoint

• Method: POST
• URL: https://data.sonla.gov.vn/api/data/sync

3. Header bắt buộc

• X-API-KEY: API Key được cấp riêng cho từng đơn vị.
• Authorization: Basic Auth từ tài khoản đăng tải dữ liệu (username:password đã encode base64).
• Content-Type: application/json

4. Cách sử dụng

Gửi request lên API với phương thức POST, đi kèm đầy đủ Header và cấu trúc Body thông báo thay đổi dữ liệu dưới dạng JSON.

Cấu trúc Body (JSON):

{
  "UUID": "UUID_QUY_TRINH",
  "operation": "CREATE",
  "data": [
    {
      "MA_KY": "ID_001"
    },
    {
      "MA_KY": "ID_002"
    },
    {
      "MA_KY": "ID_003"
    }
  ]
}

Ví dụ lệnh cURL:

curl --location 'https://data.sonla.gov.vn/api/data/sync' \
--request POST \
--header 'X-API-KEY: your_api_key_here' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic your_base64_auth_here' \
--data '{
  "UUID": "UUID_QUY_TRINH",
  "operation": "CREATE",
  "data": [
    { "MA_KY": "ID_001" },
    { "MA_KY": "ID_002" },
    { "MA_KY": "ID_003" }
  ]
}'

5. Quy định tần suất gọi

• Mỗi lần gọi API phải cách nhau tối thiểu 5 phút.
• Nếu gọi sớm hơn hệ thống sẽ từ chối phản hồi dữ liệu mới.

6. Kết quả trả về

✔️ Thành công (HTTP Status: 200)

{
  "success": true,
  "message": "Đồng bộ dữ liệu thành công"
}

❌ Các lỗi thường gặp

Thiếu API Key (HTTP Status: 401)

{
  "error_code": 401,
  "message": "X-API-KEY là bắt buộc trong header"
}

API Key không hợp lệ (HTTP Status: 403)

{
  "error_code": 403,
  "message": "API Key không hợp lệ"
}

Gọi quá nhanh (< 5 phút) (HTTP Status: 429)

{
  "error_code": 429,
  "message": "Vui lòng thử lại sau 5 phút",
  "next_sync_time": "YYYY-MM-DD HH:mm:ss"
}

Có lỗi trong quá trình xử lý (HTTP Status: 500)

{
  "error_code": 500,
  "message": "Có lỗi xảy ra trong quá trình đồng bộ"
}

7. Lưu ý quan trọng

• 🔑 Bảo mật: Không chia sẻ API Key ra ngoài dưới mọi hình thức.
• ⏱️ Tần suất: Tuân thủ thời gian gọi API (≥ 5 phút/lần).
• 🌐 Kết nối: Đảm bảo server cài đặt có thể kết nối thông suốt tới API trục.