เอกสารอ้างอิง API

การอนุญาตบัญชี

ตรวจสถานะ QR

ตรวจผลของ flow QR จนกว่าผู้ให้บริการจะรายงานสำเร็จหรือไม่สำเร็จ QR ที่รอสแกนจะส่ง auth_payload.qr_code ล่าสุด ส่วน WhatsApp อาจส่ง passkey_required พร้อม auth_payload.public_key สำหรับขั้นตอน WebAuthn ถัดไปแทน

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

ช่องทางที่รองรับ

TelegramWhatsAppLINEZaloTikTok

ก่อนเรียกใช้

ใช้ X-Api-Key ของ workspace เจ้าของทรัพยากรบนเซิร์ฟเวอร์ แทนค่าตัวอย่างทั้งหมดก่อนเรียกใช้

ที่มาของพารามิเตอร์
account_id
รับ data.id จากการสร้างหรือค้นหาบัญชี รหัสเป็นของ workspace ที่ระบุด้วย X-Api-Key ดูบัญชี

พารามิเตอร์คำขอ

ส่วนหัว

X-Api-Key
stringจำเป็น

API key ของพื้นที่ทำงาน ระบบจะระบุพื้นที่ทำงานจากส่วนหัวนี้

Content-Type
stringจำเป็น

ใช้ application/json เมื่อต้องส่งเนื้อหาของคำขอเป็น JSON

พารามิเตอร์ใน path

account_id
stringจำเป็น

ตัวระบุที่ใช้ใน route ของ authentication

เนื้อหาของคำขอ

จุดเชื่อมต่อนี้รับออบเจ็กต์ JSON ว่าง โปรดส่ง {} ตามตัวอย่างคำขอ

ทำความเข้าใจผลลัพธ์

อ่าน status/auth_status และ auth_payload ที่ส่งกลับจริงสำหรับคำสั่งยืนยันตัวตนนี้ หากต้องให้ผู้ใช้ดำเนินการ ให้ทำตามคู่มือช่องทาง authorized หมายถึงยืนยันตัวตนเสร็จ แต่ก่อนส่งข้อความต้องตรวจ runtime_status ด้วย

การตอบกลับ 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>"
    }
  }
}

การตอบกลับ 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>"
      }
    }
  }
}

เนื้อหาการตอบกลับ

provider
string

รหัสช่องทาง ใช้ค่าที่ API ส่งกลับโดยไม่แก้ไขในการเรียกครั้งต่อไป ดูค่าที่ API นี้คืนได้จาก enum ด้านล่าง

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

action
string

การดำเนินการที่ร้องขอในการเรียกครั้งนี้

status
string

สถานะ flow การให้สิทธิ์ปัจจุบัน เช่น pending_auth, awaiting_qr_scan, awaiting_code, pending, passkey_required, passkey_pending, passkey_confirmation, passkey_confirmation_sent, authorized หรือ failed

auth_status
string

สถานะการยืนยันตัวตนมาตรฐานปัจจุบัน เช่น awaiting_qr_scan, awaiting_code, passkey_required, authorized หรือ failed ให้ดำเนินขั้นตอนอนุญาตของช่องทางที่เกี่ยวข้องต่อตามค่านี้

auth_payload
object

payload มาตรฐานที่ต้องใช้ในขั้นปัจจุบัน QR ใช้ qr_code; ขั้นยืนยัน code ใช้ type=code; Passkey ใช้ type=passkey และ public_key payload ของขั้นที่แยกกันจะไม่ปรากฏพร้อมกัน

type
string

ชนิด payload ของขั้นปัจจุบัน code หมายถึงขั้นยืนยัน code และ passkey หมายถึงขั้น Passkey

qr_code
string

เนื้อหา QR สำหรับแสดงเฉพาะเมื่อ auth_status เป็น awaiting_qr_scan

public_key
object

WebAuthn PublicKeyCredentialRequestOptions ที่ส่งให้ browser credentials API เมื่อ auth_status เป็น passkey_required

account_id
string

บัญชีของผู้ให้บริการที่การตอบกลับนี้อ้างถึง

expires_at
string

timestamp แบบ RFC3339 ที่หลังจากนั้น auth_payload ปัจจุบันจะไม่ใช้ได้แล้ว

การตอบกลับ

200

200 OK

คำขอสำเร็จ ดูตัวอย่างเนื้อหาตอบกลับด้านบน

400

Bad Request

เนื้อหาของคำขอ path หรือพารามิเตอร์ไม่ถูกต้อง

401

Unauthorized

ส่วนหัว X-Api-Key หายไปหรือไม่ถูกต้อง

409

Conflict

การดำเนินการขัดแย้งกับบัญชีของผู้ให้บริการหรือทรัพยากรที่มีอยู่

500

Internal Server Error

บริการพบข้อผิดพลาดที่ไม่คาดคิด

502

Bad Gateway

อะแดปเตอร์หรือ upstream provider ไม่สามารถทำรายการให้เสร็จได้

เมื่อคำขอล้มเหลว

ตรวจ HTTP และ error.code/numeric_code เก็บ request_id แล้วแก้พารามิเตอร์ ยืนยันตัวตนต่อ หรือตรวจ runtime ตามสาเหตุ ตรวจผลครั้งก่อนก่อนส่งหรือเขียนซ้ำ อ้างอิงรหัสข้อผิดพลาด

invalid_request · 10000 · 400
ตรวจฟิลด์บังคับ รูปแบบ และเงื่อนไขช่องทาง แล้วแก้คำขอ
missing_api_key · 11000 · 401
ตรวจ X-Api-Key และว่า workspace ยังใช้งานอยู่
invalid_api_key · 11001 · 401
ตรวจ X-Api-Key และว่า workspace ยังใช้งานอยู่