การยืนยันตัวตน API และเริ่มต้นใช้งาน

Dureach ให้ทรัพยากร API สำหรับลูกค้าผ่านเส้นทางที่มีเวอร์ชัน /api/ แอปยังมีเส้นทางภายใน /api/v1/ และ /api/v2/ ด้วย เส้นทางภายในไม่ได้เป็น API สาธารณะโดยอัตโนมัติ ให้ใช้เฉพาะเส้นทางที่ระบุใน เอกสารอ้างอิง API

สร้างคีย์

1. เปิด Settings → Integrations ในแอป
2. เปิดส่วน OAuth service account และสร้างคีย์ด้วยสิทธิ์ขั้นต่ำที่จำเป็น
3. ตั้งชื่อที่ชัดเจน เลือกเฉพาะ scope ที่ integration ต้องใช้ คัดลอกคีย์ครั้งเดียวไปยังตัวจัดการความลับฝั่งเซิร์ฟเวอร์ และใช้ YOUR_OAUTH_ACCESS_TOKEN ในเอกสารกับตัวอย่าง
4. หากคีย์ถูกเปิดเผย ให้ revoke แล้วสร้างคีย์ใหม่ ห้ามวางคีย์ใน browser bundle, URL, ภาพหน้าจอ, issue หรือ log

ยืนยันตัวตน

ส่งคีย์ใน header Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN เก็บคีย์ให้พ้นจาก browser bundle, URL, ภาพหน้าจอ, issue และ log คำขอจะอยู่ภายใต้ workspace ที่สร้างคีย์และกำลังใช้งานอยู่

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

ทรัพยากรจัดการ OAuth service account และ webhook อยู่ที่ /oauth/service-accounts, /api/v2/webhooks ตรวจสิทธิ์และ entitlement ของ workspace ก่อนสร้าง integration

รูปแบบ request และ response

สร้างคีย์ด้วย JSON body ที่มี name และ array scopes ที่ไม่ว่าง response การสร้างมี id, name, scopes, key, workspace_id, timestamp_created และ timestamp_updated ระบบคืนค่า key เต็มเพียงครั้งเดียว การอ่านครั้งถัดไปจะแสดงเฉพาะ prefix ที่ปลอดภัย

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

Response ของ list ใช้ array items และอาจมี next_starting_after ให้คง cursor นี้ตามเดิมเมื่อขอหน้าถัดไป endpoint รายการ OAuth service account และ webhook มีค่าเริ่มต้น 25 records ส่วนหน้า webhook และ webhook-event จำกัด 100 records records ของ webhook มี campaign, name, target_hook_url, event_type และ custom_interest_value; records ของ webhook event มีสถานะการส่งและฟิลด์การ retry

Checklist การใช้งาน

1. ใช้ method และ path ตามเอกสารอย่างตรงกัน เส้นทางส่วนตัวของแอปและ runner ไม่ใช่ endpoint API สำหรับลูกค้า
2. จำกัดขนาดหน้าและทำตาม field ของ cursor หรือ pagination จาก endpoint
3. ถือ 401 เป็นการยืนยันตัวตนไม่ถูกต้องหรือถูก revoke และ 403 เป็นปัญหาสิทธิ์หรือ entitlement
4. Retry เฉพาะ server failure ชั่วคราว ใช้ backoff ที่มีขอบเขตและกลยุทธ์ idempotency สำหรับ write อย่า retry 400, 401, 403, 404, 409 หรือ 429 แบบไม่ตรวจสาเหตุ
5. เก็บ request ID และ error code ที่ลบข้อมูลสำคัญแล้วสำหรับ support อย่าเก็บ key หรือ payload ส่วนตัว

ทำให้ webhook consumer เป็น idempotent: เก็บ event ID ก่อน acknowledge ตรวจ signature เมื่อมีการตั้งค่า และรองรับ delivery retry

ข้อผิดพลาด

Error ของ OAuth service account ใช้ JSON ที่มี statusCode, error และ message; endpoint รุ่นใหม่อาจมี code ที่อ่านโดยเครื่องได้ ให้ถือ 400 เป็น input ไม่ถูกต้อง 401 เป็น authentication failure 403 เป็น authorization หรือ entitlement failure 404 เป็น resource ไม่รู้จัก และ 429 เป็น rate หรือ usage limit อย่า retry response 4xx แบบไม่ตรวจสาเหตุ

หน้าที่เกี่ยวข้อง

ดู API webhooks และ ขีดจำกัดการใช้งาน

ตาราง authentication failure

การตรวจสอบอย่างปลอดภัย

เรียก read-only request ก่อน ยืนยัน workspace ใน response และรูปแบบ items แล้วเก็บ cursor next_starting_after ตามที่ส่งกลับมา สำหรับ write ให้บันทึกเฉพาะ HTTP status, error code ที่ลบข้อมูลสำคัญแล้ว และ request ID ห้ามบันทึก bearer key หรือ webhook payload