Tham chiếu API

Ủy quyền tài khoản

Kiểm tra xác thực QR

Kiểm tra luồng QR cho đến khi nhà cung cấp báo thành công hoặc thất bại. QR đang chờ trả về auth_payload.qr_code mới nhất; WhatsApp có thể trả về passkey_required cùng auth_payload.public_key cho bước WebAuthn tiếp theo.

POSThttps://api.unifyport.ai/v1/accounts/{account_id}/auth/qr/check

Kênh được hỗ trợ

TelegramWhatsAppLINEZaloTikTok

Trước khi gọi

Dùng X-Api-Key của workspace sở hữu tài nguyên trên máy chủ. Thay mọi giá trị mẫu trước khi chạy.

Nguồn tham số
account_id
Lấy data.id từ phản hồi tạo hoặc truy vấn tài khoản. ID thuộc workspace của X-Api-Key. Lấy tài khoản

Tham số yêu cầu

Tiêu đề

X-Api-Key
stringbắt buộc

API key của không gian làm việc. Không gian làm việc được xác định từ tiêu đề này.

Content-Type
stringbắt buộc

Dùng application/json khi gửi nội dung yêu cầu JSON.

Tham số đường dẫn

account_id
stringbắt buộc

Định danh dùng cho route authentication.

Nội dung yêu cầu

Điểm cuối này nhận một đối tượng JSON rỗng; hãy gửi {} như trong ví dụ yêu cầu.

Hiểu kết quả

Đọc status/auth_status và auth_payload thực sự trả về cho thao tác xác thực này. Nếu cần người dùng thao tác, làm theo hướng dẫn của kênh. authorized nghĩa là xác thực hoàn tất; trước khi gửi vẫn phải kiểm tra runtime_status.

Phản hồi awaiting_qr_scan

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "provider": "whatsapp",
    "action": "check_qr_auth",
    "status": "awaiting_qr_scan",
    "auth_status": "awaiting_qr_scan",
    "auth_payload": {
      "qr_code": "<QR_CODE>"
    }
  }
}

Phản hồi passkey_required

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "provider": "whatsapp",
    "action": "check_qr_auth",
    "status": "passkey_required",
    "auth_status": "passkey_required",
    "auth_payload": {
      "type": "passkey",
      "public_key": {
        "challenge": "<BASE64URL_CHALLENGE>"
      }
    }
  }
}

Nội dung phản hồi

provider
string

Mã định danh kênh. Dùng nguyên giá trị API trả về trong các lần gọi sau; xem enum bên dưới để biết giá trị của API này.

enum: telegram, whatsapp, line, twitter, zalo, tiktok, whatsapp-protocol

action
string

Hành động được yêu cầu trong lần gọi này.

status
string

Trạng thái hiện tại của luồng ủy quyền, ví dụ pending_auth, awaiting_qr_scan, awaiting_code, pending, passkey_required, passkey_pending, passkey_confirmation, passkey_confirmation_sent, authorized hoặc failed.

auth_status
string

Trạng thái xác thực chuẩn hóa hiện tại, ví dụ awaiting_qr_scan, awaiting_code, passkey_required, authorized hoặc failed. Tiếp tục quy trình ủy quyền của kênh tương ứng theo giá trị này.

auth_payload
object

Payload chuẩn cần cho bước hiện tại. QR dùng qr_code; bước xác minh mã dùng type=code; Passkey dùng type=passkey và public_key. Payload của các bước loại trừ nhau không xuất hiện cùng lúc.

type
string

Loại payload của bước hiện tại; code biểu thị bước xác minh mã và passkey biểu thị bước Passkey.

qr_code
string

Nội dung QR chỉ hiển thị khi auth_status là awaiting_qr_scan.

public_key
object

WebAuthn PublicKeyCredentialRequestOptions truyền vào browser credentials API khi auth_status là passkey_required.

account_id
string

Tài khoản nhà cung cấp mà phản hồi này tham chiếu tới.

expires_at
string

Dấu thời gian RFC3339 mà sau đó auth_payload hiện tại không còn hợp lệ.

Phản hồi

200

200 OK

Yêu cầu thành công. Xem ví dụ nội dung phản hồi.

400

Bad Request

Body, đường dẫn hoặc tham số yêu cầu không hợp lệ.

401

Unauthorized

Header X-Api-Key thiếu hoặc không hợp lệ.

409

Conflict

Thao tác đang yêu cầu xung đột với tài khoản hoặc tài nguyên nhà cung cấp đã có.

500

Internal Server Error

Dịch vụ gặp lỗi không mong muốn.

502

Bad Gateway

Adapter hoặc upstream provider không thể hoàn tất thao tác.

Khi yêu cầu thất bại

Kiểm tra HTTP và error.code/numeric_code, giữ request_id. Sửa tham số, tiếp tục xác thực hoặc kiểm tra runtime tùy nguyên nhân. Xác nhận kết quả cũ trước khi thử lại thao tác gửi hoặc ghi. Tham chiếu mã lỗi

invalid_request · 10000 · 400
Kiểm tra trường bắt buộc, định dạng và điều kiện kênh rồi sửa yêu cầu.
missing_api_key · 11000 · 401
Kiểm tra X-Api-Key và workspace còn hoạt động.
invalid_api_key · 11001 · 401
Kiểm tra X-Api-Key và workspace còn hoạt động.