Skip to main content
Version: 1.0

Hướng dẫn kết nối​

1. Giới thiệu​

Để đảm bảo an toàn và kiểm soát truy cập, GEdu sẽ cung cấp cho đối tác hai thông tin quan trọng: Access Key và Secret Key. Mỗi yêu cầu gửi đến API đều cần đính kèm hai thông tin này nhằm xác thực và đảm bảo tính toàn vẹn của dữ liệu.

  • Access Key: Là mã định danh duy nhất, dùng để xác thực quyền truy cập vào hệ thống GEdu.

  • Secret Key: Là khóa bí mật của mỗi trường được sử dụng để tạo chữ ký số (Signature) cho từng yêu cầu API.

2. Bảo mật và lưu ý​

Yêu cầu bảo mật:

  • Mỗi đối tác chỉ được cấp một Access Key

  • Mỗi trường thuộc đối tác sẽ được một Secret Key tương ứng.

  • Tuyệt đối không chia sẻ hoặc công khai hai thông tin này cho bên thứ ba dưới bất kỳ hình thức nào.

  • Nếu nghi ngờ bị lộ hoặc cần cấp mới, vui lòng liên hệ đội ngũ kỹ thuật GEdu để được hỗ trợ kịp thời.

3. Hướng dẫn sử dụng​

3.1: Xác thực Access Key:​

Yêu cầu: Mỗi request gửi lên API đều phải đính kèm Access Key.

Gắn vào HTTP Header theo định dạng: X-Access-Key: <Access Key>

3.2: Quy trình tạo Signature:​

  • 3.2.1: Đối với phương thức GET​

    Api yêu cầu thông tin request gồm:

    Tham sốGiá trị
    SchoolCodeTHCSAnPhu001
    Timestamp1719378600
    SignatureGiá trị chữ ký tính được

    Bước 1: Tạo chuỗi PlainText: Mỗi Api sẽ có một chuỗi PlainText riêng. Ghép các tham số theo đúng thứ tự định nghĩa API. (không được thay đổi key, thứ tự hoặc thêm khoảng trắng)

      schoolCode=THCSAnPhu001&timestamp=1719378600

    Bước 2: Tạo Signature: Tính toán HMAC-SHA256 trên Secret Key và dữ liệu PlainText (UTF-8)

    Thuật toán: HMACSHA256(PlainText, Secret Key)

      string plainText = "schoolCode=THCSAnPhu001&timestamp=1719378600";
      string secretKey = "mySecretKey123";

      using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secretKey));
      byte[] hashBytes = hmac.ComputeHash(Encoding.UTF8.GetBytes(plainText));
      string signature = Convert.ToBase64String(hashBytes);

    Bước 3: Đính kèm signature vào request. vì Signature có dạng base64 nên cần URL encoding ("+", "/", "=" thành "%2B", "%2F", và "%3D") trước khi gửi qua URL để tránh gây lỗi

  • 3.2.2 Đối với phương thức POST​

    Bước 1: Chuyển data request sang dạng Json.

    Property theo camelCase (ví dụ: schoolCode, timestamp, v.v...) và được sắp xếp theo kí tự alphabet (A-Z).

    Giả sử object gốc:

      {
        "schoolName": "Tiểu học An Phú",
        "schoolCode": "THCSAnPhu001",
        "description": "demo object"
      }

    Sau khi sắp xếp alphabet:

      {
        "description":"demo object",
        "schoolCode":"THCSAnPhu001",
        "schoolName":"Tiểu học An Phú"
      }

    Bước 2: Tạo Signature: Tính toán HMAC-SHA256 trên Secret Key và OrderCamelJson

    Thuật toán: HMACSHA256(OrderCamelJson, Secret Key)

    Bước 3: Gắn signature vào body payload.

4. Cấu Hình HTTP Request​

KeyValue
MethodGet, Post
Content-Typeapplication/json
Domainhttps://sandbox-integrate-api.geducation.vn

5. Client gửi request:​

  • Hướng dẫn gọi vào api: {Domain}/api/edu/v1

  • Nếu API là GET:

    GET {Domain}/api/edu/v1/reporting-rounds?SchoolCode=ABC123&Timestamp=1719378600&Signature=2eGh2dsJKqv96WxIm4KFVMZT4Q6OqHTmZwhBqHwjF0=

    Gọi API bằng curl:

      curl -X GET "{Domain}/api/edu/v1/reporting-rounds?SchoolCode=ABC123&Timestamp=1719378600&Signature=2eGh2dsJKqv96WxIm4KFVMZT4Q6OqHTmZwhBqHwjF0=" \
           -H "X-Access-Key: YOUR_ACCESS_KEY"

  • Nếu API là Post:

    Header yêu cầu:

      X-Access-Key: YOUR_ACCESS_KEY
      Content-Type: application/json

    Payload:

      {
        "schoolCode": "ABC123",
        "timestamp": 1719378600,
        "signature": "2eGh2dsJKqv96WxIm4KFVMZT4Q6OqHTmZwhBqHwjF0="
      }

6. Xử lý lỗi liên quan đến Access Key​

HTTP StatusÝ nghĩa
400 Bad RequestSignature hoặc thông tin chưa chính xác
401 UnauthorizedThông tin Access key không chính xác, vui lòng liên hệ hỗ trợ

7. Liên hệ hỗ trợ​