Tổng quan

1.1. Endpoint & Variables

Các biến số dưới đây sẽ được sử dụng trong tài liệu này

Tên biến	Mô tả	STAGING	PRODUCTION
AUTHORIZATION_SERVER	Domain tích hợp API lấy access token	https://iam-staging.gam.vn	https://iam.gam.vn
RESOURCE_SERVER	Domain tích hợp open API	https://gateway-staging.gam.vn/oms	https://gateway.gam.vn/oms

Tên biến	Mô tả
MESSAGE	Thông báo trả về của API
ERROR_MESSAGE	Mô tả lỗi
LOG_ID	Log Id cho tracing
STATUS_CODE	Mã HTTP status code

1.2. Xác thực,

Hệ thống sử dụng OAuth2 với grant type client_credentials để cấp quyền truy cập API. Bạn cần gọi Token Endpoint để lấy access_token, sau đó dùng token này để gọi các API nghiệp vụ.

OAuth2 Client Credentials Grant Flow

API lấy Access token

Token Endpoint

POST {AUTHORIZATION_SERVER}/oauth2/v3/token

Header

Content-Type: application/x-www-form-urlencoded

Body parameters

Parameter	Required	Description
grant_type	Yes	Luôn là client_credentials.
client_id	Yes	ID của ứng dụng được cấp từ IAM.
client_secret	Yes	Secret gắn với client_id (phải được bảo mật).
scope	Yes	Danh sách quyền cần cấp, phân tách bởi dấu cách. Ví dụ: iam:user-password:update gamp:erp.customer-reconciliation.write-direct.

cURL Example

curl --location '{{AUTHORIZATION_SERVER}}/oauth2/v3/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=iam:user-password:update gamp:erp.customer-reconciliation.write-direct' \
--data-urlencode 'client_secret=YOUR_CLIENT_SECRET' \
--data-urlencode 'client_id=YOUR_CLIENT_ID'

Response

{
  "access_token": "eyJraWQiOiJrM2F...",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "iam:user-password:update gamp:erp.customer-reconciliation.write-direct"
}

Response data

Tham số	Mô tả
access_token	Token bạn sẽ dùng để gọi API.
expires_in	Thời gian sống của token (tính bằng giây, mặc định là 1 ngày).
token_type	Luôn là Bearer.
scope	Quyền hạn được cấp trong token.

1.3. Request format

API hỗ trợ định dạng dữ liệu là aplication/json. Các request cần set giá trị trên cho header Content-Type Khi gọi API nghiệp vụ, bạn cần gửi header Authorization kèm access_token đã nhận được

info

• Giá trị mặc định của Content-Type là aplication/json

Example

POST /api/v1/authenticated HTTP/1.1
Host: {RESOURCE_SERVER}
X-Client-Source: `PARTNER_CODE`
Authorization: Bearer eyJraWQiOiJrM2F...

{"field1":value1,"field2":value2}

1.4. Định dạng phản hồi

Với request xác thực thất bại

HTTP/1.1 403 Forbidden Content-Type:application/json; charset=UTF-8 Content-Length: 0

Với request xác thực thành công

Content type: JSON

{
  "status": "{STATUS_CODE}",
  "message":"{MESSAGE}",
  "timestamp": "...",
  "data": "..."
}

Với request xác thực thành công nhưng gặp lỗi xử lý

Content type: JSON

{
  "status": "{STATUS_CODE}",
  "message": "{ERROR_MESSAGE}",
  "error_code": "{ERROR_CODE}",
  "timestamp": "..."
}