บัญชี

รายชื่อบัญชี

แสดงบัญชีของผู้ให้บริการใน พื้นที่ทำงานปัจจุบัน สถานะการยืนยันตัวตนของบัญชีอยู่ใน จุดเชื่อมต่อ กลุ่ม Authentication

GEThttps://api.unifyport.ai/v1/accounts

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

all

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

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

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

ส่วนหัว

X-Api-Key

stringจำเป็น

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

พารามิเตอร์ Query

limit

integer

จำนวนบัญชีสูงสุดต่อหน้า ตั้งแต่ 1 ถึง 100 ค่าเริ่มต้นคือ 20 เมื่อละไว้ ค่าที่ไม่ถูกต้องหรือการส่ง limit ซ้ำจะคืน 400 invalid_request (numeric_code=10000) สามารถปรับค่านี้เมื่อขอหน้าถัดไปได้

minimum: 1 · maximum: 100

cursor

string

เคอร์เซอร์แบบ opaque สำหรับรายการบัญชี ละไว้หรือส่งสตริงว่างเพื่ออ่านหน้าแรก สำหรับหน้าถัดไปให้ส่ง data.next_cursor จากการตอบกลับก่อนหน้าโดยไม่แก้ไข ใช้ได้เฉพาะ workspace ที่ออกเคอร์เซอร์นั้น การส่ง cursor ที่ไม่ถูกต้อง ส่งซ้ำ หรือใช้ข้าม workspace จะคืน 400 invalid_request (numeric_code=10000)

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

จุดเชื่อมต่อนี้ไม่ต้องใช้เนื้อหา JSON

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

อ่านบัญชีจาก data.items หาก data.has_more=true ให้ส่ง data.next_cursor เดิมเป็น cursor เพื่อเรียกหน้าถัดไป สถานะยืนยันตัวตนต้องเรียกดูแยกจาก API ยืนยันตัวตน

การตอบกลับ 200 OK

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "items": [
      {
        "id": "acc_example",
        "name": "Telegram Production",
        "provider": "telegram",
        "region": "global",
        "status": "active",
        "runtime_status": "running",
        "auth_mode": "qrcode",
        "capabilities": [
          "send_message",
          "receive_message"
        ],
        "metadata": {
          "env": "production"
        },
        "provider_account_ref": "provider-side-identifier",
        "provider_profile": {
          "id": "778899",
          "phone": "8600000000000",
          "username": "production_bot",
          "display_name": "Production Bot",
          "first_name": "Production",
          "last_name": "Bot",
          "avatar_url": "https://example.com/avatar.jpg",
          "bio": "Customer support"
        }
      }
    ],
    "has_more": false
  }
}

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

provider_profile

object

โปรไฟล์ที่ผู้ให้บริการรายงาน เช่น display_name จะถูกละไว้ก่อนที่บัญชีจะยืนยันตัวตน

id

string

ตัวระบุแบบ opaque ของบัญชีในช่องทางที่เชื่อมต่อ สำหรับ WhatsApp อาจเป็น canonical LID ที่ไม่มี suffix ของอุปกรณ์

device_id

integer

หมายเลขอุปกรณ์ที่เข้าสู่ระบบ ซึ่งอาจปรากฏในรายละเอียดบัญชี WhatsApp เมื่อระบุเซสชันปัจจุบันได้ อาจเปลี่ยนหลังยืนยันตัวตนใหม่และไม่ใช่รหัสอุปกรณ์ถาวร

minimum: 0 · maximum: 65535

phone

string

หมายเลขโทรศัพท์ที่ normalize แล้ว ไม่มีช่องว่าง ขีด หรือเครื่องหมาย + นำหน้า

username

string

username ที่ provider รายงาน ถ้ามี

display_name

string

ชื่อแสดงผลของบัญชี สำหรับ WhatsApp จะสร้างโดยให้ BusinessName มาก่อนและใช้ PushName เป็นค่าทดแทน

push_name

string

PushName ที่ตั้งอยู่บนบัญชี WhatsApp ปัจจุบัน provider อื่นไม่ได้กำหนดความหมายของฟิลด์นี้

business_name

string

WhatsApp BusinessName; จะละฟิลด์นี้เมื่อ provider ไม่ส่งค่ากลับมา

first_name

string

ชื่อที่ provider รายงาน ถ้ามี

last_name

string

นามสกุลที่ provider รายงาน ถ้ามี

avatar_url

string

URL รูปประจำบัญชีที่ provider รายงาน

bio

string

ประวัติหรือข้อความสถานะที่ provider รายงาน

platform

string

ตัวระบุแพลตฟอร์มการเข้าสู่ระบบที่ WhatsApp รายงานระหว่างการจับคู่ ให้ถือเป็นสตริงทึบและรองรับค่าที่ไม่รู้จัก provider อื่นไม่ได้กำหนดความหมายของฟิลด์นี้ และฟิลด์นี้ต่างจาก device_platform

billing

object

รอบที่จ่ายแล้วเฉพาะบัญชีกระเป๋า ห้ามอนุมานซื้อจากยอดเงิน

period_start_at

string

เริ่มรอบที่จ่ายแล้วจากเซิร์ฟเวอร์

format: date-time

period_end_at

string

สิ้นสุดรอบที่จ่ายแล้วจากเซิร์ฟเวอร์

format: date-time

amount_minor

integer

ยอดคงที่จากเซิร์ฟเวอร์หน่วยเซนต์ USD ใช้จำนวนเต็มแม่นยำ

minimum: 1 · format: int64

currency

string

เฉพาะ USD

operation_id

string

รหัสสาธารณะจาก billing.operation_id หรือผลลบ ใช้เดิมในพื้นที่เดิม

state

string

สถานะคิดเงินหรือการดำเนินการ ไม่ยืนยันตัวตน ออนไลน์ หรือคืนเงินแล้ว

enum: ACTIVE, DELETING, DELETED, COMPENSATED, REVIEW

id

string

ตัวระบุบัญชีที่ไม่ซ้ำ (acc_...) ใช้ใน route ที่อิงกับบัญชี

name

string

ชื่อบัญชีที่อ่านได้

provider

string

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

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

region

string

ภูมิภาคทางออกเครือข่ายเริ่มต้นที่เลือกสำหรับบัญชี

status

string

สถานะ lifecycle ของบัญชี เช่น active

runtime_status

string

สถานะ runtime ที่ปรับเป็นมาตรฐาน หนึ่งในค่า unknown, starting, running, stopping, stopped, reconnecting, disconnected หรือ error

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

auth_mode

string

flow การยืนยันตัวตนที่บัญชีใช้: code, qrcode หรือ session โดย TikTok รองรับ qrcode และ session แต่ไม่รองรับการสลับระหว่างสองโหมดนี้ในบัญชีเดิม

capabilities[]

string[]

ความสามารถที่เปิดใช้สำหรับบัญชี เช่น send_message และ receive_message

metadata

object

label สภาพแวดล้อมของคุณเองที่เก็บไว้บนบัญชี

provider_account_ref

string

ตัวระบุฝั่งผู้ให้บริการที่คุณแนบได้เพื่อเชื่อมโยงบัญชีกับระบบของคุณเอง

proxy

object

proxy ที่ลูกค้ากำหนดไว้อย่างชัดเจน โดยไม่ส่งคืนข้อมูลรับรองของทางออกเริ่มต้นของแพลตฟอร์ม

has_more

boolean

ระบุว่ารายการบัญชียังมีหน้าถัดไปหรือไม่

next_cursor

string

เคอร์เซอร์แบบ opaque สำหรับหน้าถัดไปของรายการบัญชี คืนค่าเฉพาะเมื่อ has_more=true ให้ส่งกลับเป็น cursor โดยไม่แก้ไขเพื่ออ่านหน้าถัดไป ฟิลด์นี้จะถูกละไว้ในหน้าสุดท้าย

การตอบกลับ

200

200 OK

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

400

Bad Request

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

401

Unauthorized

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

403

Forbidden

ระบบระบุคำขอได้ แต่ไม่อนุญาตให้ดำเนินการนี้

404

Not Found

ไม่พบทรัพยากรที่ร้องขอ โปรดตรวจสอบ error.code ร่วมกับการดำเนินการปัจจุบัน

500

Internal Server Error

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

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

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

อ่านสถานะ HTTP, error.code และ error.numeric_code ร่วมกับคำสั่งที่เรียก รหัสตัวเลขเป็นสตริง เก็บ request_id เพื่อตรวจปัญหา ค่านี้ไม่ใช่คีย์ป้องกันการทำซ้ำหรือรหัสงาน

invalid_request · 10000 · 400

ตรวจ JSON และฟิลด์ที่จำเป็น

วิธีจัดการและลองใหม่: แก้พารามิเตอร์ตามคำสั่งและเงื่อนไขช่องทางก่อนเรียกใหม่ การส่งคำขอผิดแบบเดิมซ้ำไม่ช่วยแก้ข้อผิดพลาด

JSON ตัวอย่าง โดย message เปลี่ยนตามสาเหตุจริง · 400 · 10000

{
  "request_id": "req_example",
  "error": {
    "code": "invalid_request",
    "numeric_code": "10000",
    "message": "Invalid request parameters"
  }
}

invalid_target_workspace · 11003 · 400

เวิร์กสเปซเป้าหมายที่กำหนดทับว่างหรือรูปแบบไม่ถูกต้อง ให้ลบเฮดเดอร์กำหนดทับและใช้ API Key ของเวิร์กสเปซเป้าหมาย

เงื่อนไข: ใช้เมื่อคำขอมีเฮดเดอร์ X-Workspace-Id เพื่อระบุเวิร์กสเปซทับ

JSON ตัวอย่าง โดย message เปลี่ยนตามสาเหตุจริง · 400 · 11003

{
  "request_id": "req_example",
  "error": {
    "code": "invalid_target_workspace",
    "numeric_code": "11003",
    "message": "Invalid target workspace"
  }
}

invalid_api_key · 11001 · 401

ตรวจว่า API Key ถูกต้องและเปิดใช้งานอยู่

วิธีจัดการและลองใหม่: เก็บ request_id และรหัสแบบมีโครงสร้าง ตรวจคำสั่งปัจจุบันก่อนเลือกการดำเนินการถัดไป

JSON ตัวอย่าง โดย message เปลี่ยนตามสาเหตุจริง · 401 · 11001

{
  "request_id": "req_example",
  "error": {
    "code": "invalid_api_key",
    "numeric_code": "11001",
    "message": "Invalid API key"
  }
}

missing_api_key · 11000 · 401

เพิ่มส่วนหัว X-Api-Key

ตัวอย่าง · 401 · 11000

{
  "request_id": "req_xxx",
  "error": {
    "code": "missing_api_key",
    "numeric_code": "11000",
    "message": "Missing X-Api-Key header"
  }
}

workspace_override_forbidden · 11002 · 403

คำขอพยายามระบุเวิร์กสเปซทับโดย API Key นี้ไม่มีสิทธิ์ ให้ลบเฮดเดอร์กำหนดทับและใช้ API Key ของเวิร์กสเปซเป้าหมาย

เงื่อนไข: ใช้เมื่อคำขอมีเฮดเดอร์ X-Workspace-Id เพื่อระบุเวิร์กสเปซทับ

JSON ตัวอย่าง โดย message เปลี่ยนตามสาเหตุจริง · 403 · 11002

{
  "request_id": "req_example",
  "error": {
    "code": "workspace_override_forbidden",
    "numeric_code": "11002",
    "message": "Workspace override is not allowed"
  }
}

target_workspace_not_found · 11004 · 404

ไม่พบเวิร์กสเปซที่กำหนดทับหรือใช้งานไม่ได้ ตรวจเจ้าของเวิร์กสเปซ ลบเฮดเดอร์กำหนดทับ และใช้ API Key ของเวิร์กสเปซเป้าหมาย การส่งซ้ำไม่เพิ่มสิทธิ์

เงื่อนไข: ใช้เมื่อคำขอมีเฮดเดอร์ X-Workspace-Id เพื่อระบุเวิร์กสเปซทับ

วิธีจัดการและลองใหม่: ตรวจรหัสเป้าหมาย เจ้าของทรัพยากร และเวิร์กสเปซปัจจุบัน อย่าถือว่าเป้าหมายที่ยืนยันแล้วว่าไม่มีหรือเข้าไม่ถึงเป็นความขัดข้องชั่วคราวที่ควรลองซ้ำอัตโนมัติ

JSON ตัวอย่าง โดย message เปลี่ยนตามสาเหตุจริง · 404 · 11004

{
  "request_id": "req_example",
  "error": {
    "code": "target_workspace_not_found",
    "numeric_code": "11004",
    "message": "Target workspace not found"
  }
}

list_accounts_failed · 20000 · 500

รายชื่อบัญชี: บริการไม่สามารถให้ผลการค้นหาที่ใช้ได้

วิธีจัดการและลองใหม่: เก็บ request_id และตรวจรหัสเป้าหมายกับสิทธิ์เข้าถึงของบัญชี ตรวจสาเหตุก่อนอ่านใหม่ การค้นหาล้มเหลวไม่ได้แปลว่าข้อมูลว่างหรือไม่มีทรัพยากร

JSON ตัวอย่าง โดย message เปลี่ยนตามสาเหตุจริง · 500 · 20000

{
  "request_id": "req_example",
  "error": {
    "code": "list_accounts_failed",
    "numeric_code": "20000",
    "message": "Failed to list accounts"
  }
}