Dureach cung cấp tài nguyên API cho khách hàng qua các route có phiên bản /api/. Ứng dụng cũng có route nội bộ /api/v1/ và /api/v2/. Route nội bộ không tự động là API công khai; chỉ dùng path trong tài liệu API.
Tạo key
- Mở Settings → Integrations trong ứng dụng.
- Mở khu vực OAuth service account và tạo key với quyền tối thiểu cần thiết.
- Đặt tên rõ ràng, chỉ chọn scope mà integration cần, copy key một lần vào secret manager phía server và dùng
YOUR_OAUTH_ACCESS_TOKENtrong tài liệu cùng ví dụ. - Nếu key bị lộ, revoke và tạo key thay thế; không dán key vào browser bundle, URL, ảnh chụp, issue hay log.
Xác thực
Gửi key trong header Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN. Giữ key ngoài browser bundle, URL, ảnh chụp, issue và log. Request thuộc workspace đang hoạt động đã tạo key.
curl --fail-with-body 'https://app.dureach.com/api/v2/webhooks?limit=25' \\
-H 'Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN' \\
-H 'Accept: application/json'Tài nguyên quản lý OAuth service account và webhook nằm ở /oauth/service-accounts, /api/v2/webhooks và /api/v2/webhook-events. Kiểm tra quyền và entitlement của workspace trước khi xây integration.
Dạng request và response
Tạo key với JSON body có name và mảng scopes không rỗng. Response tạo gồm id, name, scopes, key, workspace_id, timestamp_created và timestamp_updated. Full key chỉ trả về một lần; các lần đọc sau chỉ hiển thị prefix an toàn.
{
"name": "Reporting integration",
"scopes": ["campaigns:read"]
}Response list dùng mảng items và có thể có next_starting_after. Giữ nguyên cursor khi lấy trang tiếp theo. Endpoint list OAuth service account và webhook mặc định 25 record; trang webhook và webhook-event tối đa 100 record. Webhook record có campaign, name, target_hook_url, event_type, custom_interest_value; webhook event record có trạng thái delivery và field retry.
Checklist vận hành
- Dùng đúng method và path được tài liệu hóa; route riêng của ứng dụng và runner không phải endpoint API khách hàng.
- Giới hạn page size và làm theo field cursor hoặc pagination của endpoint.
- Xem
401là lỗi xác thực không hợp lệ hoặc đã revoke, và403là lỗi quyền hoặc entitlement. - Chỉ retry lỗi server tạm thời, dùng backoff giới hạn và chiến lược idempotency cho write. Không retry mù các response
400,401,403,404,409hoặc429. - Lưu request ID và mã lỗi đã che dữ liệu nhạy cảm để gửi support, không lưu key hoặc payload riêng tư.
Làm webhook consumer có tính idempotent: lưu event ID trước khi acknowledge, kiểm tra signature khi được cấu hình và chịu được delivery retry.
Lỗi
Lỗi OAuth service account dùng JSON có statusCode, error, message; endpoint mới có thể thêm code máy đọc được. Xem 400 là input không hợp lệ, 401 là lỗi xác thực, 403 là lỗi authorization hoặc entitlement, 404 là resource không biết, 429 là rate hoặc usage limit. Không retry mù response 4xx.
Trang liên quan
Xem API webhooks và giới hạn sử dụng.
Bảng lỗi xác thực
| HTTP status | Ý nghĩa | Cách sửa |
|---|---|---|
| 400 | JSON, field, cursor hoặc limit không hợp lệ. | Xác thực request và dùng enum/value được tài liệu hóa. |
| 401 | Bearer key thiếu, không hợp lệ hoặc đã revoke. | Gửi Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN; thay key đã revoke. |
| 403 | Scope, role, workspace hoặc plan không cho phép thao tác. | Thêm scope cần thiết hoặc nhờ workspace admin bật quyền. |
| 404 | Resource hoặc path không tồn tại. | Xác nhận version, UUID và danh sách endpoint công khai. |
| 429 | Giới hạn rate hoặc sử dụng. | Theo hướng dẫn response và retry với backoff giới hạn. |
Xác minh an toàn
Chạy request chỉ đọc trước, xác nhận workspace trong response và dạng items, rồi lưu cursor next_starting_after đúng như trả về. Với write, chỉ log HTTP status, mã lỗi đã che và request ID. Không bao giờ log bearer key hoặc webhook payload.