Biz API

​An toàn thông tin với Biz API

Để đảm bảo an toàn thông tin khi phát hành voucher, Got It áp dụng các biện pháp như sau:

​Whitelist IP của client khi gọi API

Môi trường stg:

  • Nếu IP location ngoài Việt Nam: Client cầng cung cấp IP để Got It add vào whitelist

Môi trường production:

  • Chỉ các IP trong whitelist của Got It mới call được API nên client cần cung cấp IP.
  • Limit max 3000 request trong 5 phút.

​Thêm key vào header khi gọi API

Xem phần Key Credential phía dưới

​Mã hóa bất đối xứng RSA (hai chiều)

Để chứng thực dữ liệu khi client call API. Got It cung cấp cơ chế mã hóa bất đối xứng RSA hay còn gọi là hệ mã hóa public key, nó sử dụng một cặp key để mã hóa và giải mã: public key (khóa công khai) dùng để mã hóa và private key dùng để giải mã.

Got It và đối tác sẽ tạo ra cặp private và public key có độ dài là 2048 bit, 2 bên sẽ trao đổi public key.

  • Khi client call đến Got It, client sẽ dùng private key của mình ký trên dữ liệu gửi đi theo quy tắc được Got It định nghĩa. Got It sẽ dùng public key mà đối tác cung cấp để xác thucwj dữ liệu là đúng và được gửi từ phía client.
  • Got It sẽ dùng private key của mình ký trên dữ liệu trả về, đối tác sẽ dùng public key Got It cung cấp để xác thực chữ ký.

​Các bước tích hợp

  1. GotIt và client sẽ cùng tạo cặp private và public key theo chuẩn RSA 2048 bit và trao đổi public key với nhau. Public key sẽ có dạng như sau:
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvjVsj2Ry7hBDJZYky+Oi
ZZTN49MUeEbXEOrQzuckWi3fQDSH7s0F7rG3gLX33W0C0SeEOUty1TIZyfbpCMuU
……………………………………………………………………………………………………………………………
………………………………………………………………………………………………………………………………..
elJ7PfaAZT2m/qT+bsvtMo2nSFEJ1SgyinYZTR5jyyJXVRydUR+hNanSNgXctMSb
RwIDAQAB
-----END PUBLIC KEY-----
plain

2. Khi gọi API /api/v4.0/vouchers/v, /api/v4.0/vouchers/g, /api/v4.0/vouchers/e, /v4.0/vouchers/multiple/status/:transactionRefId, phía client cần truyền thêm tham số signature (được mã hóa SHA256 with RSA và base64) vào body params. GotIt sẽ xác thực signature này, nếu đúng sẽ tiến hành xử lý API, nếu sai sẽ báo lỗi (3003: The signature is incorrect).

3. Signature được tạo từ access code có cú pháp tương ứng cho các API như sau

  • Cú pháp access code khi gọi API /api/v4.0/vouchers/v, /api/v4.0/vouchers/g:
[API Key]|orderName|expiryDate|transactionRefId
plain
  • Cú pháp access code khi gọi API /api/v4.0/vouchers/e:
[API Key]|transactionRefId
plain
  • Cú pháp access code khi gọi API /v4.0/vouchers/multiple/status/:transactionRefId:
[API Key]|transactionRefId
plain

4. Response từ Got It sẽ đính kèm chữ ký của Got It ở header, đối tác sẽ xác thực chữ ký dựa trên public key của Got It cung cấp và toàn bộ nội dung response.

​Mã hóa thông tin voucher dùng client public key

Got It dùng client public key để mã hóa dữ liệu trả về. Client sẽ dùng private key để giải mã. Voucher trả về sẽ có dạng như sau:

Biz API Encryption With Public Key

​Key Credential

Tất cả yêu cầu gửi đến phải chứa trường 'X-GI-Authorization' trên header, API Key do Got It cung cấp. Đây là mã bí mật, duy nhất chỉ cung cấp cho khách hàng, khách hàng có trách nhiệm bảo mật. Khách hàng để lộ API Key X-GI-Authorization sẽ phải chịu trách nhiệm cho mọi voucher phát sinh từ phía API Key này.

Thông tin này sẽ thay đổi theo từng môi trường, khách hàng nên để chúng trong cấu hình của application.

Cách tích hợp Got It Biz APIBảng mã lỗi của Biz API