API đối tác

Xác thực OAuth2.0

📘

OAuth 2.0 chỉ hoạt động trên điểm cuối / quảng cáo

Khi tích hợp báo cáo đơn hàng qua API, bạn sẽ cần tích hợp điểm cuối đơn hàng với tính năng xác thực Cơ bản và mã API bí mật của mình.

ID Ứng dụng khách và Bí mật Ứng dụng khách

Mã client_id và client_secret sẽ do Người quản lý tài khoản kỹ thuật của bạn cung cấp. Bí mật ứng dụng khách là dữ liệu riêng tư và không nên được chia sẻ.

Yêu cầu Mã token Truy cập

Để lấy mã token truy cập, bạn phải gửi một yêu cầu có chứa client_id và client_secret. Để làm vậy, nhà bán lẻ phải thực hiện yêu cầu POST tới điểm cuối Máy chủ ủy quyền CitrusAd:

https://$BASE_URL/v1/oauth2/token

📘

/oauth2/token chỉ cung cấp mã thông báo có liên quan. Bạn sẽ sử dụng các mã token này để tương tác với các điểm cuối tích hợp khác nhau.

Để thực hiện được yêu cầu, bạn phải gửi Ủy quyền cơ bản qua tiêu đề yêu cầu Ủy quyền có chứa base64 được mã hóa client_id và client_secret của Nhà bán lẻ:

Authorization: "Basic" + base64encode(client_id + ":" + client_secret)

Bạn phải bổ sung thông số sau dưới định dạng application/x-www-form-urlencoded trong nội dung yêu cầu HTTP:

grant_type=client_credentials

Yêu cầu sẽ giống như sau:

POST https://$BASE_URL/v1/oauth2/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic <base64 encoded id+key>
grant_type=client_credentials

Nhận Mã token Truy cập của bạn

Phản hồi sẽ chứa các thông tin sau

  • access_token: Mã token truy cập sẽ được sử dụng khi gọi các API CitrusAd
  • expires_in: Số lượng, tính bằng giây, cho đến khi mã token truy cập hết hạn
  • token_type: Loại mã token được trả về. Nó sẽ luôn là Bearer trong trường hợp này

Dưới đây là một phản hồi mẫu

{
  "access_token": "xxxxx.yyyyy.zzzzz",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Sử dụng Mã token

Lệnh gọi các điểm cuối API CitrusAd có thể được thực hiện bằng cách thêm duy nhất mã token truy cập vào tiêu đề Ủy quyền trên yêu cầu
Authorization: “Bearer “ <access_token>

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Bearer <access_token>
{
    "customerId": "wertg5432a",
    "sessionId": "ec9-4e07-881d-3e9", 
    "placement": "category",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
         ["category:Cupboard/Snacks"]
    ],
    "options": {
                             "filterMode": "AndOr"
                             },
    "maxNumberOfAds": 3
}

Lỗi yêu cầu

Ứng dụng khách không hợp lệ

Nếu client_id hoặc client_secret gửi trong yêu cầu bị sai thì bạn sẽ nhận được phản hồi như sau:

{
  "error": "invalid_client"
}

Kiểm tra xem thông tin đăng nhập bạn dùng có đúng không. Kiểm tra kỹ client_id và client_secret và đảm bảo bạn đang sử dụng Ủy quyền cơ bản một cách chính xác khi gọi điểm cuối/token.
##Yêu cầu không hợp lệ
Lỗi yêu cầu không hợp lệ sẽ được trả về từ Máy chủ Ủy quyền nếu yêu cầu thiếu một tham số bắt buộc, bao gồm giá trị tham số không hợp lệ, bao gồm một tham số nhiều lần hoặc bị định dạng sai.

{
  "error": "invalid_request"
}

Hãy đảm bảo:

  • Chỉ đưa grant_type=client_credentials vào nội dung yêu cầu
  • Đặt Content-Type chính xác làm tiêu đề yêu cầu