Tài liệu tham khảo Dureach API: xác thực, endpoint, phân trang và webhook

Trang này mô tả bề mặt Dureach API an toàn cho khách hàng: quản lý OAuth service account, webhook và lịch sử delivery, cùng endpoint thu thập contact tách phiên bản. Nội dung gồm xác thực, field, dạng response, cursor pagination, filter, giới hạn và lỗi cần xử lý trong production.

Bắt đầu với phạm vi được hỗ trợ

Tạo key trong Settings -> Integrations với quyền tối thiểu. Giữ key ở server, gửi qua header Authorization và giới hạn mọi request vào workspace đích. Ứng dụng trình duyệt, private runner và route chưa được tài liệu hóa /api/v1/ hoặc /api/v2/ không tự động là customer API.

Ví dụ dùng https://app.dureach.com. Thay YOUR_OAUTH_ACCESS_TOKEN và UUID bằng giá trị của bạn. Không đặt key thật trong browser bundle, URL, screenshot, log hoặc ticket hỗ trợ.

Hướng dẫn

Xác thực

Gửi key dưới dạng bearer token trong mọi 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 thuộc workspace đã tạo key và không thể vượt ranh giới workspace. Nếu request trả 401, hãy thu hồi key nếu có thể đã lộ, tạo key thay thế và cập nhật secret phía server.

Endpoint OAuth service account

Mọi endpoint OAuth service account nằm dưới /oauth/service-accounts và cần scope OAuth business scopes tương ứng (hoặc all:*).

`POST /oauth/service-accounts`

Tạo key. Request cần name không rỗng (tối đa 255 ký tự) và mảng scopes không rỗng. Tên scope phải hợp lệ và không lặp. Giá trị đầy đủ của key chỉ được trả trong response này.

{
  "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`

Liệt kê key trong workspace đang hoạt động. Tham số query:

Tham số	Bắt buộc	Chi tiết
`limit`	Không	Số record, mặc định 25. Dùng số nguyên dương; server giới hạn kích thước trang.
`starting_after`	Không	UUID của key cuối trang trước. Gửi `next_starting_after` nguyên vẹn.

Response có items và next_starting_after khi còn trang tiếp theo. Lần đọc sau chỉ trả prefix key an toàn, không trả secret gốc.

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

Thu hồi key. Response có metadata của key đã xóa và prefix an toàn. Coi thao tác xóa thành công là vĩnh viễn và xóa key khỏi secret manager.

Endpoint webhook

Endpoint webhook nằm dưới /api/v2, cần webhooks:* (hoặc all:*) và plan có webhook.

`GET /api/v2/webhooks`

Liệt kê đích webhook. Filter hỗ trợ là campaign (UUID campaign) và event_type. Dùng limit và starting_after để phân trang cursor. Kích thước trang 1-100, mặc định 25. Response là:

{
  "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`

Tạo đích. Gửi target_hook_url, name, event_type và custom_interest_value nếu event là nhãn quan tâm tùy chỉnh. campaign là tùy chọn cho event cấp workspace.

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

Đọc, cập nhật hoặc xóa một đích. PATCH nhận cùng field như lúc tạo và chỉ đổi field được gửi. Xác nhận đích sau khi update; xóa đích không xóa event delivery lịch sử.

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

Trả các event type chuẩn cùng event nhãn lead tùy chỉnh trong workspace. Dùng id trả về làm event_type; không hard-code nhãn có thể đổi tên.

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

Gửi delivery test. Response thành công có success: true, status_code: 200, response_time_ms và error: null. Test với receiver không phải production trước.

`GET /api/v2/webhook-events`

Liệt kê các lần delivery. Lọc bằng success=true|false hoặc webhook_url. Dùng limit (1-100, mặc định 25) và starting_after. Event gồm payload, status_code, success, retry_count, will_retry, timestamp_next_retry, error_message, retry_successful, lead_email và response_time_ms. Che payload và lead_email trước khi ghi log.

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

Đọc một lần delivery theo UUID.

`GET /api/v2/webhook-events/summary` và `GET /api/v2/webhook-events/summary-by-date`

Trả tình trạng delivery tổng hợp. Summary gồm total_events, successful_events, failed_events, success_rate và failure_rate. Summary theo ngày trả mảng items một record mỗi ngày. Dùng để monitor, không dùng replay event.

Endpoint thu thập contact

Dịch vụ thu thập contact hiện cung cấp các endpoint legacy có meter riêng dưới /api/v1/leadbank. Khả dụng phụ thuộc entitlement workspace:

Method	Path	Mục đích
`POST`	`/api/v1/leadbank/find`	Tìm contact bằng payload tìm kiếm được hỗ trợ.
`POST`	`/api/v1/leadbank/acquire_email`	Yêu cầu reveal email công việc của contact đủ điều kiện.
`GET`	`/api/v1/leadbank/balance/get`	Đọc số dư thu thập hiện tại.
`GET`	`/api/v1/leadbank/acquire-lists`	Liệt kê acquisition list.
`GET`	`/api/v1/leadbank/acquire-lists/{list_id}/leads`	Liệt kê lead trong một acquisition list.
`GET`	`/leadbank/api/v1/company/{company_id}`	Đọc record công ty đã thu thập.

Response tìm kiếm và list có thể lớn. Luôn gửi tham số page hoặc limit được tài liệu hóa và dừng khi không còn trang tiếp theo. Kết quả trống nghĩa là query không có match, không chứng minh người hay công ty không tồn tại.

Vệ sinh request

Dùng method và path được tài liệu hóa, kiểm tra field trước khi gửi, tuân cursor hoặc giới hạn trang, và xử lý riêng 401, 403, validation, rate và lỗi server. Làm webhook consumer idempotent: lưu event ID trước khi acknowledge và retry an toàn sau lỗi tạm thời.

Lỗi

Quản lý OAuth service account trả JSON có statusCode, error và message; endpoint mới có thể có code. Coi 400 là input không hợp lệ, 401 là xác thực thiếu, sai hoặc bị thu hồi, 403 là lỗi scope, role, workspace hoặc plan, 404 là resource không biết, 409 là xung đột trạng thái và 429 là giới hạn rate hoặc usage. Chỉ retry request bounded, idempotent sau lỗi 5xx tạm thời; không retry mù quáng 4xx.

Checklist khắc phục sự cố

Xác nhận base URL https://app.dureach.com và phiên bản path đúng.
Gửi Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN; không dùng key trong query string.
Kiểm tra scope key và workspace hiện tại, rồi xác nhận plan có endpoint.
Xác minh UUID, field bắt buộc, phạm vi limit và cursor starting_after.
Ghi status, message hoặc code đã che, thời điểm request và endpoint để hỗ trợ.
Thu hồi và thay key nếu bị lộ. Không gửi key hoặc webhook payload chưa che.

Quy trình endpoint

Tạo OAuth service account trong Settings → Integrations và chọn scope nhỏ nhất.
Gửi request chỉ đọc với Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN và Accept: application/json.
Xác minh dạng response trước khi viết integration; giữ items, UUID, enum và next_starting_after.
Dùng cursor pagination đúng như response trả về và dừng khi không còn cursor.
Làm webhook consumer idempotent bằng cách lưu event ID trước khi acknowledge.

Quy tắc field của request

Dùng limit dương có giới hạn, UUID hợp lệ, event type được tài liệu hóa và đủ field JSON bắt buộc. Không đặt key trong query string, browser bundle, screenshot hoặc log.

API campaign và lead

Đây là các thao tác campaign và lead được hỗ trợ bằng OAuth service account theo workspace. Tạo key trong Settings -> Integrations, lưu giá trị khi được hiển thị một lần và giữ key ở phía máy chủ. Gói workspace phải có quyền truy cập API. Dùng https://api.dureach.com cho các request dưới đây.

Phương thức	Đường dẫn	Quyền cần có	Mục đích
`GET`	`/api/v2/campaigns`	`campaigns:read`	Liệt kê campaign
`POST`	`/api/v2/campaigns`	`campaigns:create`	Tạo campaign
`GET`	`/api/v2/campaigns/{id}`	`campaigns:read`	Xem campaign
`PATCH`	`/api/v2/campaigns/{id}`	`campaigns:update`	Cập nhật campaign
`POST`	`/api/v2/lead/add`	`leads:create`	Thêm lead vào campaign
`GET`	`/api/v2/lead/get`	`leads:read`	Tìm lead theo email
`POST`	`/api/v2/lead/update/status`	`leads:update`	Cập nhật trạng thái lead

Bắt đầu bằng request chỉ đọc:

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

Danh sách campaign trả về items và có thể có next_starting_after. Giữ nguyên cursor này trong request kế tiếp. limit tối đa là 100. Dùng UUID trong response để xem hoặc cập nhật một campaign.

Để thêm lead, gửi JSON sau tới POST /api/v2/lead/add:

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

Tra cứu lead bằng GET /api/v2/lead/get?email=jane%40example.com&campaign_id=CAMPAIGN_UUID. Để đổi trạng thái, gửi campaign_id, email và new_status tới POST /api/v2/lead/update/status. Tạo và cập nhật campaign dùng JSON; xem OpenAPI schema để biết các trường lịch và sequence bắt buộc.

Key gắn với workspace tạo ra nó. X-Workspace-ID khác sẽ bị từ chối. Key thiếu hoặc không hợp lệ trả 401; thiếu scope hoặc sai workspace trả 403. Xử lý riêng lỗi xác thực dữ liệu và giới hạn request. Không đặt key trong URL, browser bundle, ảnh chụp hay log.

Hợp đồng OpenAPI mô tả trường request, response và bearer auth cho bảy thao tác này.

Bắt đầu với phạm vi được hỗ trợ

Hướng dẫn

Xác thực

Endpoint OAuth service account

POST /oauth/service-accounts

GET /oauth/service-accounts

DELETE /oauth/service-accounts/{id}

Endpoint webhook

GET /api/v2/webhooks

POST /api/v2/webhooks

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

GET /api/v2/webhooks/event-types

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

GET /api/v2/webhook-events

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

GET /api/v2/webhook-events/summary và GET /api/v2/webhook-events/summary-by-date