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

AuthorizeShop

post

Body

application/json

emailstringOptional

external_shop_idstringOptional

external_user_idstringOptional

extra_tokenstringOptional

namestringOptional

phonestringOptional

redirect_urlstringOptional

shop_idstring · int64Optional

shop_namestringOptional

Responses

200

A successful response

application/json

post

$BASE_URL.Shop/AuthorizeShop

HTTPcURLJavaScriptPython

POST $BASE_URL.Shop/AuthorizeShop HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 198

{
  "config": [
    "shipment"
  ],
  "email": "text",
  "external_shop_id": "text",
  "external_user_id": "text",
  "extra_token": "text",
  "name": "text",
  "phone": "text",
  "redirect_url": "text",
  "shop_id": "text",
  "shop_name": "text"
}

200

A successful response

{
  "auth_token": "text",
  "auth_url": "text",
  "code": "text",
  "expires_in": 1,
  "meta": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "msg": "text",
  "type": "text"
}

Request:

curl --location '$BASE_URL.Shop/AuthorizeShop' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer $API_KEY' \
--data '{
  "shop_id": "<int64>",
  "redirect_url": "<string>"
}'

Response

{
    "auth_token": "string",
    "auth_url": "string",
    "code": "string",
    "expires_in": 0,
    "meta": {
        "property1": "string",
        "property2": "string"
    },
    "msg": "string",
    "type": "string"
}

Cấu trúc body của request:

Tham số	Kiểu dữ liệu	Mô tả
shop_id	string	ID của shop
redirect_url	string	Redirect sau khi shop đăng nhập thành công

Cấu trúc thuộc tính dữ liệu trả về:

Tham số	Kiểu dữ liệu	Mô tả
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

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 đăng nhập thành công:

export REDIRECT_URL="https://example.com/redirect?token=87209412&shop_id=12414"

Đối tác nên đính kèm token hoặc thông tin shop của đối tác trong redirect_url để xác định được shop tương ứng khi nhận redirect.

Quá trình kết nối với shop:

1. Gửi request đến .Shop/AuthorizeShop.

2. 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ừ ITS.

3. Gửi lại request với shop_id nhận được.

4. Lưu shop_id và auth_token để sử dụng trong các API khác.

Kết nối lần đầu

Trường hợp shop của đối tác đã từng kết nối với ITS và đối tác đã có thông tin shop_id thì bỏ qua bước này. Trong trường hợp shop của đối tác chưa từng kết nối với ITS, đối tác có thể gửi request như sau:

# Mặc định
curl $BASE_URL.Shop/AuthorizeShop \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $API_KEY" \
    -d '{
        "shop_id": "<id của shop do ITS cung cấp>"
        "redirect_url": "'$REDIRECT_URL'"
    }'

# Hoặc cung cấp thông tin sẵn có (các mục là không bắt buộ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'"
    }'

Kết nối lần thứ hai trở đi

Trong trường hợp shop của đối tác đã từng kết nối với ITS, đối tác cần có thông tin shop_id. Gửi request như sau:

# 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 ITS 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 để ITS redirect về sau khi shop đăng nhập thành công.

Xử lý kết quả

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.interits.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, ITS 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>.

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.

Lưu ý: cần lưu ý rằng kể cả khi shop đã từng kết nối với ITS, nhưng shop vẫn có thể được yêu cầu đăng nhập lại. Tình huống này xảy ra khi shop đã gỡ liên kết với tài khoản của đối tác. Lúc này, response sẽ có type=shop_request và auth_url được trả về, đối tác cần redirect về địa chỉ này để shop đăng nhập lại.

Kiểm tra shop_key

Để kiểm tra shop_key nhận được là đúng, đối tác có thể gửi request đến:

CurrentShop

post

Body

application/json

objectOptional

Responses

200

A successful response

application/json

post

$BASE_URL.Shop/CurrentShop

HTTPcURLJavaScriptPython

POST $BASE_URL.Shop/CurrentShop HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 2

{}

200

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ề:

Tham số	Kiểu dữ liệu	Mô tả
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 ITS 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 ITS 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.