Tham chiếu API

Kết nối tài khoản

Refresh trạng thái runtime

Đồng bộ trạng thái runtime mới nhất của nhà cung cấp cho tài khoản. runtime_status nhận một trong các giá trị chuẩn của nền tảng: unknown, starting, running, stopping, stopped, reconnecting, disconnected, error. Các nhãn riêng của từng provider được chuẩn hoá về tập giá trị này trước khi trả về.

POSThttps://api.unifyport.ai/v1/accounts/{account_id}/runtime/refresh

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.

Hoàn tất xác thực và kiểm tra runtime_status. Xác thực và kết nối là hai trạng thái riêng; HTTP thành công chưa chứng minh sẵn sàng.

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 runtime.

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 runtime_status; starting hoặc reconnecting cần kiểm tra tiếp. Nếu auth_required=true, tiếp tục xác thực. Thiếu cờ này không chứng minh tài khoản trực tuyến.

Phản hồi 200 OK

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "account_id": "acc_example",
    "runtime_status": "running"
  }
}

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.

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 runtime đã yêu cầu.

enum: refresh_status, start, stop, reconnect

operation_status
string

Trạng thái cho biết hành động runtime đã được chấp nhận hoặc hoàn tất.

runtime_status
string

Trạng thái runtime đã chuẩn hoá: một trong unknown, starting, running, stopping, stopped, reconnecting, disconnected hoặc error.

enum: unknown, starting, running, stopping, stopped, reconnecting, disconnected, error

runtime_error
string

Lỗi runtime của provider khi hành động không thể hoàn tất.

auth_required
boolean

Khi true, tiếp tục quy trình ủy quyền của kênh. Chỉ trả về khi kênh cung cấp dữ liệu ủy quyền hoặc có quy trình đã xác nhận nhưng chưa hoàn tất. Thiếu trường hoặc false không có nghĩa là trực tuyến; hãy xem runtime_status. Chỉ có disconnected không đủ để kết luận cần ủy quyền lại. API runtime không trả về code, qrcode, auth_payload hoặc provider_data; lấy dữ liệu từ API ủy quyền của kênh.

auth_status
string

Trạng thái ủy quyền tùy chọn, ví dụ pending, awaiting_qr_scan hoặc passkey_required. Được trả về khi có dữ liệu ủy quyền hoặc quy trình đang thực hiện đã được xác nhận. Làm theo hướng dẫn kênh; lấy trạng thái và dữ liệu đầy đủ từ API ủy quyền, xem trạng thái kết nối ở runtime_status.

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_not_ready · 30009 · 409
Khôi phục xác thực và kết nối, xác nhận kết quả cũ trước khi thử lại.