Sử dụng
Mô hình kết nối

Cấu hình
Sử dụng api_key
được cung cấp và cấu hình như sau:
export API_KEY=<AuthToken>
export API_HOST=<base_url>
Hướng dẫn sử dụng các lệnh export
và curl
được cung cấp sẵn khi chạy bằng terminal trên hệ điều hành Linux hoặc Mac. Trong trường hợp bạn sử dụng môi trường khác, vui lòng thay thế bằng các thao tác tương đương.
Cấu trúc API
Request
Một lời gọi API tiêu biểu như sau:
curl --location '$BASE_URL.Misc/CurrentAccount \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $API_KEY" \
-d '{}'
Tất cả request sử dụng giao thức HTTPS, method POST và truyền giá trị bằng body sử dụng định dạng dữ liệu application/json
. Các header bắt buộc là Content-Type
và Authorization
.
Response
Response sử dụng định dạng dữ liệu application/json
được set trong header Content-Type
. Nếu request thành công, HTTP status code là 200
. Nếu request lỗi, HTTP status code có thể là 4xx
hoặc 5xx
với cấu trúc tương tự như sau:
{
"code": "invalid_argument",
"msg": "..."
}
Kết nối tài khoản shop
Việc kết nối được thực hiện theo mô hình redirect. Đối tác cần chuẩn bị một địa chỉ url để nhận redirect sau khi shop được khởi tạo thành công:
export REDIRECT_URL="https://example.com/redirect?token=87209412&shop_id=12414"
Quá trình kết nối với shop:
Gửi request đến .Shop/AuthorizeShop.
Redirect đến địa chỉ url được cung cấp bởi
auth_url
, chờ shop xác thực tài khoản và nhận redirect từ eTelecom.Gửi lại request với
shop_id
nhận được.Lưu
shop_id
vàauth_token
để sử dụng trong các API khác.
curl $BASE_URL.Shop/AuthorizeShop \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $API_KEY" \
-d '{
"email": "<địa chỉ email>",
"phone": "<số điện thoại>",
"name": "<tên>",
"redirect_url": "'$REDIRECT_URL'"
}'
Cấu trúc body của request:
email required
string
Địa chỉ email tài khoản shop muốn tạo
phone
required
string
Số điện thoại tài khoản shop muốn tạo
name
required
string
Tên tài khoản shop muốn tạo
redirect_url required
string
Redirect sau khi shop đăng nhập thành công
200 OK type=shop_request
{
"code": "ok",
"msg": "",
"type": "shop_request",
"auth_token": "request:Ut8zhsaQp_kwKi2u2gEch_9R3yiQvpFUnB5mE_MRfks",
"expires_in": 900,
"auth_url": "https://partner-auth.etelecom.vn/login?token=request:Ut8zhsaQp_kwKi2u2gEch_9R3yiQvpFUnB5mE_MRfks"
}
Kết quả này nghĩa là shop sẽ được yêu cầu đăng nhập để xác nhận tài khoản. Kết quả trả về sẽ cung cấp một địa chỉ url bằng field auth_url
để đối tác redirect shop đến và xác thực tài khoản.
Sau khi thực hiện xác thực tài khoản, eTelecom sẽ redirect về địa chỉ url đối tác cung cấp kèm với shop_id
, theo cấu trúc: $REDIRECT_URL?token=<token>&shop_id=<shop_id>
.
Lấy thông tin shop_key
shop_key
Thông tin shop_id
được trả về trong redirect_url
khi đối tác tạo shop thành công ở bước kết nối tài khoản shop
# Sử dụng shop_id (bắt buộc)
curl $BASE_URL.Shop/AuthorizeShop \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $API_KEY" \
-d '{
"shop_id": "<id của shop do eTelecom cung cấp>",
"redirect_url": "'$REDIRECT_URL'"
}'
Đối tác vẫn cần cung cấp redirect_url
vì có thể xảy ra tình huống shop cần đăng nhập lại. Lúc này redirect_url
sẽ được sử dụng để eTelecom redirect về sau khi shop đăng nhập thành công.
Cấu trúc body của request:
shop_id
required
string
ID của shop
redirect_url
required
string
Redirect sau khi shop đăng nhập thành công
200 OK type=shop_key
{
"code": "ok",
"msg": "",
"type": "shop_key",
"auth_token": "shop1052570182707778180:KgGTCsQHSzfKBt8la63c7E6NRqqnD5RVRMrb0aJwa8jZCEbGCmJ7Q01aVwyZeGeR",
"expires_in": -1
}
Kết quả này nghĩa là đối tác đã có thể tạo tổng đài hoặc gửi zns với tư cách shop. Hãy lưu lại auth_token
ứng với tài khoản của shop để sử dụng tiếp tục, thông tin này chính là shop_key
Cấu trúc thuộc tính dữ liệu trả về:
auth_token
string
Mã ủy quyền
auth_url
string
Đường dẫn ủy quyền
code
string
Trạng thái thành công hay thất bại
expires_in
int
Thời gian hết hạn
meta
object
Thuộc tính nếu có
msg
string
Mô tả api
Kiểm tra shop_key
shop_key
Để kiểm tra shop_key
nhận được là đúng, đối tác có thể gửi request đến:
POST /CurrentShop HTTP/1.1
Host: $BASE_URL.Shop
Content-Type: application/json
Accept: */*
Content-Length: 2
{}
A successful response
{
"id": "text",
"image_url": "text",
"name": "text",
"type": "unknown",
"website": "text"
}
Request:
export API_KEY=<api_key>
curl $BASE_URL.Shop/CurrentShop \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $SHOP_KEY" \
-d '{}'
Response:
{
"id": "string",
"image_url": "string",
"name": "string",
"type": "unknown",
"website": "string"
}
Cấu trúc thuộc tính dữ liệu trả về:
id
string
ID của tài khoản
name
string
Tên tài khoản
type
string
Loại tài khoản:
Partner
Shop
Các lỗi thường gặp
400 Bad Request
{
"code": "invalid_argument",
"msg": "..."
}
Vui lòng kiểm tra lại các giá trị cung cấp.
401 Unauthorized
{
"code": "unauthenticated",
"msg": "..."
}
Vui lòng kiểm tra lại request đã bao gồm header Authorization: <api_key>
đúng.
403 Forbidden
{
"code": "permission_denied",
"msg": "...",
"meta": {
"reason": "Chỉ có thể sử dụng shop_id nếu shop đã từng đăng nhập qua hệ thống của đối tác."
}
}
Shop chưa bao giờ đăng nhập vào eTelecom thông qua hệ thống của đối tác. Hãy thử lại với request mà không bao gồm shop_id
.
Lưu ý: trong trường hợp shop từng đăng nhập vào eTelecom thông qua hệ thống của đối tác, sau đó gỡ liên kết với đối tác, kết quả trả về vẫn là 200 OK
với yêu cầu shop đăng nhập và cấp quyền lại. Nên lỗi permission_denied
chỉ xảy ra khi shop_id
được cung cấp không chính xác.
404 Not Found
{
"code": "bad_route",
"msg": "unexpected Content-Type: \"\""
}
Vui lòng kiểm tra lại path và header Content-Type: application/json
.
Last updated