1. 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
OPEN_API	Domain tích hợp open API	https://services-staging.ghtklab.com	https://services.giaohangtietkiem.vn
CUSTOMER_WEBSITE	Website quản lý đơn hàng cho khách hàng	https://khachhang-staging.ghtklab.com	https://khachhang.giaohangtietkiem.vn

Tên biến	Mô tả
API_TOKEN	API token lấy được từ web khách hàng của GHTK - URL : CUSTOMER_WEBSITE/web/thong-tin-shop/tai-khoan
PARTNER_CODE	Shop code hoặc mã bí mật dành cho đối tác
MESSAGE	Thông báo trả về của API
ERROR_MESSAGE	Mô tả lỗi
LOG_ID	Log iD for tracing
TRACKING_ORDER	Mã đơn hàng GHTK

1.2. Token header

Hướng dẫn tạo API token

• Đăng nhập tài khoản GHTK của bạn tại đường dẫn : https://khachhang.giaohangtietkiem.vn/web
• Truy cập màn hình quản lý API tokens: https://khachhang.giaohangtietkiem.vn/web/thong-tin-shop/cau-hinh-api

Ở màn hình này, bạn có thể quản lý các mã token của bạn đã tạo, thêm mới hoặc gỡ bỏ API_TOKEN.

Để tạo token mới, vui lòng bấm vào nút Tạo Token ở góc trên bên phải màn hình

• Nhập thông tin cho token của bạn
  • Tên token : Tên ghi nhớ cho dịch vụ tích hợp của bạn
  • Ngày hết hạn : Thời gian hiệu lực của token
  • Chọn các quyền truy cập cho mã token ( Tạo đơn, Tính phí đơn hàng, lấy trạng thái đơn hàng ... )

Sử dụng mã API_TOKEN để xác thực request với hệ thống OpenAPI

Request đến service API sẽ được xác thực theo giá trị Token trong header của request

GET /services/authenticated HTTP/1.1
Host: `{{OPEN_API}}`
Token: `{{API_TOKEN}}`
X-Client-Source: `{{PARTNER_CODE}}`

1.3. Request format

GHTK hỗ trợ 2 định dạng dữ liệu là application/x-www-form-urlencoded và aplication/json. Các request cần set một trong hai giá trị trên cho header Content-Type

thông tin

• API requests need to be in either x-www-form or json.
• Giá trị mặc định của Content-Type là application/x-www-form-urlencoded
• Sử dụng api /services/authenticated để kiểm tra kết nối đến hệ thống GHTK

application/x-www-form-urlencoded

POST /services/authenticated HTTP/1.1
Host: `OPEN_API`
Token: `API_TOKEN`
X-Client-Source: `PARTNER_CODE`
Content-Type:application/x-www-form-urlencoded
field1=value1&field2=value2

application/json

POST /services/authenticated HTTP/1.1
Token: `API_TOKEN`
X-Client-Source: `PARTNER_CODE`
Content-Type:application/x-www-form-urlencoded

{"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

{
  "success":true,
  "message":"{MESSAGE}",
  "log_id":"{LOG_ID}",
  "data": ".."
}

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

Content type: JSON

{
  "success": false,
  "message": "{ERROR_MESSAGE}",
  "error_code": "{ERROR_CODE}",
  "log_id": "{LOG_ID}"
}