Ủy quyền tài khoản

Bắt đầu xác thực bằng mã

Bắt đầu xác thực bằng số đã lưu. Với WhatsApp, nhập data.verify_code trên điện thoại; không gửi đến /auth/code. Với Telegram, gửi mã đã nhận đến /auth/code và chỉ gọi /auth/password khi được yêu cầu. awaiting_code không có nghĩa là xác thực thành công.

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

Kênh được hỗ trợ

TelegramWhatsApp

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

Yêu cầu

curl -X POST "https://api.unifyport.ai/v1/accounts/{account_id}/auth/start" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{}'

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 200 · WhatsApp

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "provider": "whatsapp",
    "action": "start_auth",
    "status": "awaiting_code",
    "auth_status": "awaiting_code",
    "verify_code": "ABCD-EFGH"
  }
}

Phản hồi 200 · Telegram

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "provider": "telegram",
    "action": "start_auth",
    "status": "awaiting_code",
    "auth_status": "awaiting_code",
    "auth_payload": {
      "type": "code"
    }
  }
}

Nội dung phản hồi

provider

string

Kênh của thao tác xác thực này.

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

action

string

Thao tác xác thực được yêu cầu: start_auth.

enum: start_auth

status

string

Trạng thái hiện tại. awaiting_code là chờ người dùng; authorized là đã xác thực xong.

auth_status

string

Trạng thái chuẩn của bước hiện tại, thường giống status.

verify_code

string

Mã ghép nối WhatsApp bằng số điện thoại, trực tiếp trong data. Nhập trên điện thoại, không gửi đến /auth/code. Không đảm bảo thời điểm hết hạn.

auth_payload

object

Hướng dẫn riêng của kênh. Telegram có thể trả về type=code, không bao gồm mã người dùng nhận được.

type

string

Loại hướng dẫn; code cho bước mã xác minh của Telegram.

Phản hồi

200

200 · WhatsApp

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.
account_already_authorized · 20016 · 409: Tài khoản đã được ủy quyền. Dùng lại hoặc hủy ủy quyền hiện tại trước khi bắt đầu lại.