Server-Side API

TIP

Trang này trình bày các API sử dụng cho component. Truy cập vào đây để tra cứu chi tiết toàn bộ API hoặc tải file swagger.json.

Để sử dụng component, server của đối tác chỉ cần sử dụng một API là AuthorizeShop để kết nối. Toàn bộ quá trình khởi tạo, đăng nhập và xác thực được thực hiện bởi eTop component.

Cấu hình

Sử dụng api_key được cung cấp và cấu hình như sau:

export API_KEY=<api_key>
export API_HOST=https://api.sandbox.etop.vn

Kết nối tài khoản shop

POST /v1/partner.Shop/AuthorizeShop

Đối tác có thể kết nối với shop theo hai bước như sau:

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 eTop và đối tác đã có thông tin shop_id thì bỏ qua bước này, di chuyển đến bước sau. Trong trường hợp shop của đối tác chưa từng kết nối với eTop, đối tác có thể gửi request như sau:

# Mặc định
curl https://api.sandbox.etop.vn/v1/partner.Shop/AuthorizeShop \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $API_KEY" \
    -d '{}'

# Hoặc cung cấp thông tin sẵn có (các mục là không bắt buộc)
curl https://api.sandbox.etop.vn/v1/partner.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>"
    }'

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 eTop, đố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 https://api.sandbox.etop.vn/v1/partner.Shop/AuthorizeShop \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $API_KEY" \
    -d '{
        "shop_id": "<id của shop do eTop cung cấp>"
    }'

Lưu ý

Nếu không cung cấp shop_id, shop sẽ luôn được yêu cầu đăng nhập lại. Để thuận tiện cho shop, đối tác cần lưu trữ shop_id để sử dụng.

Xử lý kết quả

200 OK type=shop_request

{
  "code": "ok",
  "msg": "Sử dụng mã này để hỏi quyền tạo đơn hàng với tư cách shop (có hiệu lực trong 15 phút)",
  "type": "shop_request",
  "auth_token": "request:Ut8zhsaQp_kwKi2u2gEch_9R3yiQvpFUnB5mE_MRfks",
  "expires_in": 900
}

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. Đối tác gửi nguyên vẹn auth_token đến client.

200 OK type=shop_key

{
  "code": "ok",
  "msg": "Sử dụng mã này để tạo đơn hàng với tư cách shop (có hiệu lực khi shop vẫn tiếp tục sử dụng dịch vụ của đối tác)",
  "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 đơn hàng với tư cách shop. Đối tác gửi nguyên vẹn auth_token đến client và lưu lại để 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 eTop, 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.

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 eTop 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 eTop 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.

409 Conflict

{
  "code": "already_exists",
  "msg": "Mã đơn hàng external_id đã tồn tại. Vui lòng kiểm tra lại.",
  "meta": {
    "duplicated": "external_id"
  }
}

Mã đơn hàng của bạn đã tồn tại ở eTop. Bạn có thể huỷ đơn cũ và thử lại. Xem thêm

Sử dụng các API khác

Đối tác có thể sử dụng shop_key có được ở trên để huỷ đơn hàng hoặc sử dụng api_key được cung cấp để nhận thay đổi qua webhook.