เอกสารอ้างอิง Dureach API: การยืนยันตัวตน endpoint pagination และ webhook

หน้านี้อธิบายพื้นผิว Dureach API ที่ลูกค้าใช้งานได้อย่างปลอดภัย ได้แก่ OAuth service account, webhook และประวัติการส่ง รวมถึง endpoint การได้มาซึ่งผู้ติดต่อที่แยกเวอร์ชัน พร้อมการยืนยันตัวตน ฟิลด์ รูปแบบผลลัพธ์ cursor pagination ตัวกรอง ขีดจำกัด และข้อผิดพลาดที่ต้องจัดการใน production.

เริ่มจากขอบเขตที่รองรับ

สร้าง OAuth service account ใน Settings -> Integrations ด้วยสิทธิ์ต่ำสุด เก็บไว้ฝั่งเซิร์ฟเวอร์ ส่งใน header Authorization และจำกัดทุก request ให้อยู่ใน workspace ที่ตั้งใจ แอปเบราว์เซอร์ private runner และ route ที่ไม่บันทึกใน /api/v1/ หรือ /api/v2/ ไม่ใช่ customer API โดยอัตโนมัติ

ตัวอย่างใช้ https://app.dureach.com ให้แทน YOUR_OAUTH_ACCESS_TOKEN และ UUID ด้วยค่าของคุณ ห้ามใส่ key จริงใน browser bundle, URL, screenshot, log หรือ ticket.

คู่มือ

การยืนยันตัวตน

ส่ง key เป็น bearer token ในทุก request:

curl --fail-with-body \
  'https://app.dureach.com/api/v2/webhooks?limit=25' \
  -H 'Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN' \
  -H 'Accept: application/json'

key เป็นของ workspace ที่สร้างและข้ามขอบเขต workspace ไม่ได้ หาก request คืนค่า 401 ให้ยกเลิก key หากอาจรั่วไหล สร้าง key ใหม่ และอัปเดต secret บนเซิร์ฟเวอร์

Endpoint OAuth service account

endpoint OAuth service account ทั้งหมดอยู่ที่ /oauth/service-accounts และต้องใช้ scope OAuth business scopes ที่ตรงกัน (หรือ all:*)

`POST /oauth/service-accounts`

สร้าง key โดย request ต้องมี name ที่ไม่ว่าง (สูงสุด 255 อักขระ) และ array scopes ที่ไม่ว่าง ชื่อ scope ต้องถูกต้องและห้ามซ้ำ ค่า key แบบเต็มคืนเฉพาะใน response นี้

{
  "name": "Reporting integration",
  "scopes": ["campaigns:read", "campaigns:create"]
}

{
  "id": "0199f372-efec-7c2d-af53-85ab8eab7c73",
  "name": "Reporting integration",
  "scopes": ["campaigns:read", "campaigns:create"],
  "key": "dureach_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "workspace_id": "0199f372-efef-73e5-b1ed-e2d1fbe4654d",
  "timestamp_created": "2025-10-17T18:33:40.079Z",
  "timestamp_updated": "2025-10-17T18:33:40.079Z"
}

`GET /oauth/service-accounts`

แสดงรายการ key ใน workspace ที่ใช้งานอยู่ พารามิเตอร์ query:

พารามิเตอร์	จำเป็น	รายละเอียด
`limit`	ไม่	จำนวน record ค่าเริ่มต้น 25 ใช้จำนวนเต็มบวก เซิร์ฟเวอร์จะจำกัดขนาดหน้า
`starting_after`	ไม่	UUID ของ key สุดท้ายจากหน้าก่อนหน้า ส่ง `next_starting_after` โดยไม่แก้ไข

response มี items และ next_starting_after เมื่อมีหน้าถัดไป การอ่านครั้งต่อไปคืนเฉพาะ prefix ของ key ที่ปลอดภัย ไม่ใช่ secret เดิม

`DELETE /oauth/service-accounts/{id}`

ยกเลิก key response มี metadata ของ key ที่ลบและ prefix ที่ปลอดภัย ถือว่าการลบสำเร็จเป็นถาวรและลบ key จาก secret manager

Endpoint webhook

Endpoint webhook อยู่ที่ /api/v2 และต้องใช้ webhooks:* (หรือ all:*) พร้อมแพ็กเกจที่มี webhook

`GET /api/v2/webhooks`

แสดงรายการปลายทาง webhook ตัวกรองที่รองรับคือ campaign (UUID ของแคมเปญ) และ event_type ใช้ limit และ starting_after สำหรับ cursor pagination ขนาดหน้า 1-100 ค่าเริ่มต้น 25 response คือ:

{
  "items": [
    {
      "id": "0199f372-efec-7c2d-af53-85ab8eab7c73",
      "campaign": "0199f372-efef-73e5-b1ed-e2d1fbe4654d",
      "name": "Interested lead receiver",
      "target_hook_url": "https://example.com/dureach-hook",
      "event_type": "lead.interested",
      "custom_interest_value": null,
      "timestamp_created": "2025-10-17T18:33:40.079Z"
    }
  ],
  "next_starting_after": "0199f372-efec-7c2d-af53-85ab8eab7c73"
}

`POST /api/v2/webhooks`

สร้างปลายทาง ส่ง target_hook_url, name, event_type และ custom_interest_value เมื่อ event เป็นป้ายกำกับความสนใจแบบกำหนดเอง campaign เป็นตัวเลือกสำหรับ event ระดับ workspace

`GET /api/v2/webhooks/{id}`, `PATCH /api/v2/webhooks/{id}`, `DELETE /api/v2/webhooks/{id}`

อ่าน อัปเดต หรือลบปลายทางหนึ่งรายการ PATCH รับฟิลด์เดียวกับการสร้างและเปลี่ยนเฉพาะฟิลด์ที่ส่ง ยืนยันปลายทางหลังอัปเดต การลบไม่ลบ event การส่งในอดีต

`GET /api/v2/webhooks/event-types`

คืนประเภท event มาตรฐานและ event ป้ายกำกับ lead แบบกำหนดเองที่มีใน workspace ใช้ id ที่คืนเป็น event_type อย่า hard-code ป้ายกำกับที่อาจเปลี่ยนชื่อ

`POST /api/v2/webhooks/{id}/test`

ส่ง delivery ทดสอบ response ที่สำเร็จมี success: true, status_code: 200, response_time_ms และ error: null ทดสอบกับ receiver ที่ไม่ใช่ production ก่อน

`GET /api/v2/webhook-events`

แสดงรายการความพยายามส่ง กรองด้วย success=true|false หรือ webhook_url ใช้ limit (1-100 ค่าเริ่มต้น 25) และ starting_after event มี payload, status_code, success, retry_count, will_retry, timestamp_next_retry, error_message, retry_successful, lead_email และ response_time_ms ปกปิด payload และ lead_email ก่อนเขียน log

`GET /api/v2/webhook-events/{id}`

อ่านความพยายามส่งหนึ่งรายการด้วย UUID

`GET /api/v2/webhook-events/summary` และ `GET /api/v2/webhook-events/summary-by-date`

คืนสุขภาพการส่งแบบรวม สรุปมี total_events, successful_events, failed_events, success_rate และ failure_rate สรุปรายวันคืน array items หนึ่ง record ต่อวัน ใช้ endpoint นี้เพื่อติดตาม ไม่ใช่เล่น event ซ้ำ

Endpoint การได้มาซึ่งผู้ติดต่อ

บริการการได้มาซึ่งผู้ติดต่อมี endpoint legacy ที่วัดแยกกันใต้ /api/v1/leadbank ความพร้อมใช้งานขึ้นอยู่กับสิทธิ์ของ workspace:

Method	Path	วัตถุประสงค์
`POST`	`/api/v1/leadbank/find`	ค้นหาผู้ติดต่อด้วย payload การค้นหาที่รองรับ
`POST`	`/api/v1/leadbank/acquire_email`	ขอเปิดเผยอีเมลงานของผู้ติดต่อที่เข้าเงื่อนไข
`GET`	`/api/v1/leadbank/balance/get`	อ่านยอดคงเหลือการได้มาปัจจุบัน
`GET`	`/api/v1/leadbank/acquire-lists`	แสดงรายการ acquisition list
`GET`	`/api/v1/leadbank/acquire-lists/{list_id}/leads`	แสดง lead ใน acquisition list หนึ่งรายการ
`GET`	`/leadbank/api/v1/company/{company_id}`	อ่าน record บริษัทที่ได้มา

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

แนวทางคำขอที่ปลอดภัย

ใช้ method และ path ที่ระบุ ตรวจฟิลด์ก่อนส่ง ทำตาม cursor หรือขีดจำกัดหน้า และจัดการ 401, 403, validation, rate และ server error แยกกัน ทำ webhook consumer ให้ idempotent เก็บ event ID ก่อน acknowledge และ retry อย่างปลอดภัยหลังความล้มเหลวชั่วคราว

ข้อผิดพลาด

การจัดการ OAuth service account คืน JSON ที่มี statusCode, error และ message endpoint ใหม่อาจมี code ด้วย ถือว่า 400 คือ input ไม่ถูกต้อง 401 คือการยืนยันตัวตนหาย ไม่ถูกต้อง หรือถูกยกเลิก 403 คือปัญหา scope, role, workspace หรือแพ็กเกจ 404 คือ resource ไม่รู้จัก 409 คือสถานะขัดแย้ง และ 429 คือ rate หรือ usage limit retry เฉพาะ request ที่ bounded และ idempotent หลัง 5xx ชั่วคราว อย่า retry 4xx แบบไม่ตรวจสอบ

เช็กลิสต์แก้ปัญหา

ยืนยัน base URL https://app.dureach.com และเวอร์ชัน path ที่ถูกต้อง
ส่ง Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN อย่าใช้ key ใน query string
ตรวจ scope ของ key และ workspace ที่ใช้งาน แล้วตรวจว่าแพ็กเกจมี endpoint นี้
ตรวจ UUID ฟิลด์จำเป็น ช่วง limit และ cursor starting_after
บันทึก status, message หรือ code ที่ปกปิดแล้ว เวลา request และ endpoint เพื่อแจ้ง support
ยกเลิกและเปลี่ยน key หากถูกเปิดเผย อย่าส่ง key หรือ webhook payload ที่ไม่ปกปิด

เวิร์กโฟลว์ endpoint

สร้าง OAuth service account ใน Settings → Integrations และเลือก scope ที่เล็กที่สุด
ส่ง request แบบอ่านอย่างเดียวพร้อม Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN และ Accept: application/json
ตรวจรูปแบบ response ก่อนสร้าง integration โดยคง items, UUID, enum และ next_starting_after ไว้
ใช้ cursor pagination ตามค่าที่คืนมาและหยุดเมื่อไม่มี cursor
ทำ webhook consumer ให้ idempotent โดยบันทึก event ID ก่อน acknowledge

กฎฟิลด์คำขอ

ใช้ค่า limit ที่เป็นบวกและอยู่ในขอบเขต UUID ที่ถูกต้อง event type ที่ระบุไว้ และฟิลด์ JSON ที่จำเป็นทั้งหมด อย่าใส่ key ใน query string, browser bundle, screenshot หรือ log

API สำหรับ campaign และ lead

นี่คือการดำเนินการ campaign และ lead ที่รองรับด้วย OAuth service account ซึ่งผูกกับ workspace สร้าง key ใน Settings -> Integrations บันทึกค่าที่แสดงเพียงครั้งเดียว และเก็บไว้ฝั่งเซิร์ฟเวอร์ แผนของ workspace ต้องมีสิทธิ์ใช้ API คำขอต่อไปนี้ใช้ https://api.dureach.com

เมธอด	พาธ	สิทธิ์ที่ต้องมี	การใช้งาน
`GET`	`/api/v2/campaigns`	`campaigns:read`	แสดงรายการ campaign
`POST`	`/api/v2/campaigns`	`campaigns:create`	สร้าง campaign
`GET`	`/api/v2/campaigns/{id}`	`campaigns:read`	อ่าน campaign
`PATCH`	`/api/v2/campaigns/{id}`	`campaigns:update`	อัปเดต campaign
`POST`	`/api/v2/lead/add`	`leads:create`	เพิ่ม lead ใน campaign
`GET`	`/api/v2/lead/get`	`leads:read`	ค้นหา lead ด้วยอีเมล
`POST`	`/api/v2/lead/update/status`	`leads:update`	อัปเดตสถานะ lead

เริ่มด้วยคำขอแบบอ่านอย่างเดียว:

curl --fail-with-body 'https://api.dureach.com/api/v2/campaigns?limit=10' \
  -H 'Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN' \
  -H 'Accept: application/json'

รายการ campaign ส่งคืน items และอาจมี next_starting_after ให้ส่ง cursor นี้โดยไม่เปลี่ยนค่าในคำขอถัดไป limit สูงสุด 100 ใช้ UUID จากผลลัพธ์เพื่ออ่านหรืออัปเดต campaign

หากต้องการเพิ่ม lead ให้ส่ง JSON นี้ไปที่ POST /api/v2/lead/add:

{
  "campaign_id": "CAMPAIGN_UUID",
  "leads": [{"email": "[email protected]", "first_name": "Jane"}]
}

ค้นหา lead ด้วย GET /api/v2/lead/get?email=jane%40example.com&campaign_id=CAMPAIGN_UUID หากต้องการเปลี่ยนสถานะ ให้ส่ง campaign_id, email และ new_status ไปที่ POST /api/v2/lead/update/status การสร้างและอัปเดต campaign ใช้ JSON ดูฟิลด์ schedule และ sequence ที่จำเป็นใน OpenAPI schema

Key ผูกกับ workspace ที่สร้างขึ้นมา ระบบปฏิเสธ X-Workspace-ID ที่ไม่ตรงกัน Key ที่หายไปหรือไม่ถูกต้องคืน 401 ส่วน scope ไม่พอหรือ workspace ไม่ตรงกันคืน 403 จัดการข้อผิดพลาดการตรวจสอบข้อมูลและการจำกัดอัตราแยกกัน อย่าใส่ key ใน URL, browser bundle, ภาพหน้าจอ หรือ log

ข้อกำหนด OpenAPI ระบุฟิลด์คำขอ ผลลัพธ์ และ bearer auth สำหรับทั้งเจ็ดการดำเนินการ

เริ่มจากขอบเขตที่รองรับ

คู่มือ

การยืนยันตัวตน

Endpoint OAuth service account

POST /oauth/service-accounts

GET /oauth/service-accounts

DELETE /oauth/service-accounts/{id}