Tham chiếu API

Ủy quyền tài khoản

Import session xác thực

Hoàn tất xác thực bằng cách import session URL hoặc cookie/session payload. Trong ví dụ client hãy dùng giá trị placeholder và không log session thật.

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

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.

WhatsApp Protocol là kênh độc lập, được xác định bằng provider=whatsapp-protocol. Hiện chỉ hỗ trợ nhập phiên (auth_mode=session), sử dụng thông tin phiên có sẵn để ủy quyền tài khoản. Ủy quyền WhatsApp Protocol

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

session_url
string

URL hoặc tham chiếu tới artifact session đã có của nhà cung cấp.

format: uri

whatsapp-protocol
object

Thông tin xác thực để nhập phiên WhatsApp Protocol, chỉ được gửi tới /v1/accounts/{account_id}/auth/session trong đối tượng lồng này, không qua provider_data. Khi cung cấp đối tượng này, bắt buộc có phone, static_pub_key, static_pri_key, identity_pub_key và identity_pri_key. Phản hồi không trả lại khóa giao thức hay thông tin xác thực nhạy cảm khác. phone dùng để kiểm tra tính nhất quán danh tính; khóa công khai và khóa riêng của giao thức chỉ dùng để khởi động phía thượng nguồn. Nền tảng chèn edge_routing cố định; bên gọi không được gửi trường này.

phone
string

Số điện thoại có thể chứa khoảng trắng, gạch nối, dấu ngoặc hoặc dấu cộng; máy chủ chuẩn hóa thành chuỗi số dương.

minLength: 1

platform
integer

Giá trị nền tảng để nhập phiên WhatsApp Protocol (int32).

format: int32

app_version
string

Phiên bản ứng dụng để nhập phiên WhatsApp Protocol.

server_address
string

Địa chỉ máy chủ provider để nhập phiên WhatsApp Protocol.

fallback_server_addresses[]
string[]

Danh sách địa chỉ máy chủ dự phòng để nhập phiên WhatsApp Protocol.

country
string

Mã quốc gia để nhập phiên WhatsApp Protocol.

device
integer

Giá trị thiết bị để nhập phiên WhatsApp Protocol (uint32).

format: uint32

static_pub_key
string

Khóa công khai của giao thức; chỉ ghi.

minLength: 1

static_pri_key
string

Khóa riêng của giao thức; chỉ ghi.

minLength: 1

identity_pub_key
string

Khóa công khai danh tính; chỉ ghi.

minLength: 1

identity_pri_key
string

Khóa riêng danh tính; chỉ ghi.

minLength: 1

hash
string

Trường tương thích đã lỗi thời; giá trị hiện bị bỏ qua và không lưu. Nên bỏ trường này.

peer_kem_public
string

Khóa công khai KEM của phía đối tác; chỉ ghi.

auth_hex_data
string

Dữ liệu xác thực hiện tại ở dạng thập lục phân; chỉ ghi.

authhexdata
string

Trường dữ liệu xác thực cũ ở dạng thập lục phân, đã lỗi thời; chỉ ghi.

pq_handshake_mode
string

Chế độ bắt tay PQ để nhập phiên WhatsApp Protocol.

use_xxkem_handshake
boolean

Có dùng bắt tay XXKEM để nhập phiên WhatsApp Protocol hay không.

Hiểu kết quả

Đọc kết quả xác thực rồi kiểm tra runtime_status. Nhập phiên và kết nối trực tuyến là hai bước khác nhau.

Phản hồi 200 OK

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "account_id": "acc_example",
    "status": "authorized"
  }
}

Nội dung phản hồi

account_id
string

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

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.

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.
invalid_api_key · 11001 · 401
Kiểm tra X-Api-Key và workspace còn hoạt động.
provider_invalid_request · 30001 · 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.