Referensi API Dureach: autentikasi, endpoint, pagination, dan webhook

Halaman ini mendokumentasikan permukaan API Dureach untuk pelanggan yang aman digunakan: pengelolaan OAuth service account, webhook dan riwayat delivery, serta endpoint akuisisi kontak yang memiliki versi terpisah. Halaman ini menjelaskan autentikasi, field, bentuk respons, cursor pagination, filter, batas, dan error yang perlu ditangani di produksi.

Start with the supported boundary

Buat OAuth service account di Settings -> Integrations dengan privilege paling rendah. Simpan di server, kirim melalui header Authorization, dan batasi setiap permintaan ke workspace yang dituju. Aplikasi browser, private runner, serta route /api/v1/ atau /api/v2/ yang tidak terdokumentasi bukan otomatis endpoint API pelanggan.

Contoh menggunakan https://app.dureach.com. Ganti YOUR_OAUTH_ACCESS_TOKEN dan UUID dengan nilai Anda. Jangan pernah menaruh key aktif di browser bundle, URL, screenshot, log, atau tiket support.

Guides

• Autentikasi dan quickstart API
• Batas akses API Dureach
• Menghubungkan klien AI melalui MCP
• Referensi tool MCP
• Persetujuan, kebijakan, dan kuota MCP
• Pembaca SQL MCP
• Pemecahan masalah MCP
• Webhook API
• Setup dan pemantauan delivery webhook

Authentication

Kirim key sebagai bearer token pada setiap permintaan:

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 dimiliki workspace aktif yang membuatnya dan tidak dapat melewati batas workspace. Jika permintaan mengembalikan 401, cabut key jika mungkin bocor, buat pengganti, dan perbarui secret di server.

OAuth service-account endpoints

Semua endpoint OAuth service account berada di /oauth/service-accounts dan memerlukan scope OAuth business scopes yang sesuai (atau all:*).

POST /oauth/service-accounts

Buat key. Permintaan memerlukan name yang tidak kosong (maksimum 255 karakter) dan array scopes yang tidak kosong. Nama scope harus valid dan tidak boleh berulang. Nilai lengkap key hanya dikembalikan pada respons ini.

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

Daftar key pada workspace aktif. Parameter query:

Respons berisi items dan, jika ada halaman berikutnya, next_starting_after. Pembacaan berikutnya hanya mengembalikan prefix key yang aman, bukan secret asli.

DELETE /oauth/service-accounts/{id}

Cabut key. Respons berisi metadata key yang dihapus dan prefix aman. Perlakukan penghapusan yang berhasil sebagai permanen dan hapus key dari secret manager.

Webhook endpoints

Endpoint webhook berada di /api/v2 dan memerlukan webhooks:* (atau all:*) serta paket yang mencakup webhook.

GET /api/v2/webhooks

Daftar tujuan webhook. Filter yang didukung adalah campaign (UUID campaign) dan event_type. Gunakan limit dan starting_after untuk cursor pagination. Ukuran halaman 1-100, default 25. Responsnya:

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

Buat tujuan. Kirim target_hook_url, name, event_type, dan jika event merupakan label minat custom, custom_interest_value. campaign opsional untuk event tingkat workspace.

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

Baca, perbarui, atau hapus satu tujuan. PATCH menerima field yang sama dan hanya mengubah field yang dikirim. Konfirmasi tujuan setelah update; menghapusnya tidak menghapus event delivery historis.

GET /api/v2/webhooks/event-types

Kembalikan tipe event standar serta event label lead custom di workspace aktif. Gunakan id yang dikembalikan sebagai event_type; jangan hard-code label custom yang dapat berganti nama.

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

Kirim delivery test. Respons sukses memiliki success: true, status_code: 200, response_time_ms, dan error: null. Uji dulu pada receiver non-production.

GET /api/v2/webhook-events

Daftar percobaan delivery. Filter dengan success=true|false atau webhook_url. Gunakan limit (1-100, default 25) dan starting_after. Event mencakup payload, status_code, success, retry_count, will_retry, timestamp_next_retry, error_message, retry_successful, lead_email, dan response_time_ms. Samarkan payload dan lead_email sebelum menulis log aplikasi.

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

Baca satu percobaan delivery berdasarkan UUID.

GET /api/v2/webhook-events/summary and GET /api/v2/webhook-events/summary-by-date

Kembalikan kesehatan delivery agregat. Ringkasan mencakup total_events, successful_events, failed_events, success_rate, dan failure_rate. Ringkasan tanggal mengembalikan array items dengan satu record per tanggal. Gunakan endpoint ini untuk monitoring, bukan replay event.

Contact acquisition endpoints

Layanan akuisisi kontak saat ini menyediakan endpoint legacy yang meternya terpisah di bawah /api/v1/leadbank. Ketersediaannya bergantung pada entitlement workspace:

Respons pencarian dan list dapat besar. Selalu kirim parameter halaman atau limit yang didokumentasikan dan berhenti saat tidak ada halaman berikutnya. Hasil kosong berarti tidak ada match untuk query tersebut; bukan informasi orang atau perusahaan tidak ada.

Request hygiene

Gunakan method dan path yang didokumentasikan, validasi field sebelum mengirim, ikuti cursor atau batas halaman, dan tangani 401, 403, validation, rate, serta server error secara terpisah. Buat consumer webhook idempotent: simpan event ID sebelum acknowledge dan retry dengan aman setelah kegagalan sementara.

Errors

Manajemen OAuth service account mengembalikan JSON berisi statusCode, error, dan message; endpoint baru dapat menyertakan code. Perlakukan 400 sebagai input invalid, 401 sebagai autentikasi hilang, invalid, atau dicabut, 403 sebagai kegagalan scope, role, workspace, atau paket, 404 sebagai resource tidak dikenal, 409 sebagai konflik status, dan 429 sebagai rate atau usage limit. Retry hanya permintaan bounded dan idempotent setelah kegagalan 5xx sementara; jangan membabi buta me-retry 4xx.

Troubleshooting checklist

1. Pastikan base URL https://app.dureach.com dan versi path benar.
2. Kirim Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN; jangan gunakan key query-string.
3. Periksa scope key dan workspace aktif, lalu pastikan paket mencakup endpoint.
4. Validasi UUID, field wajib, rentang limit, dan cursor starting_after.
5. Catat status, message atau code yang disamarkan, waktu permintaan, dan endpoint untuk support.
6. Cabut dan ganti key jika terekspos. Jangan kirim key atau payload webhook tanpa redaksi.

Endpoint workflow

1. Buat OAuth service account di Settings → Integrations dan pilih scope terkecil.
2. Kirim request read-only dengan Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN dan Accept: application/json.
3. Validasi bentuk respons sebelum membuat integrasi: pertahankan items, UUID, enum, dan next_starting_after.
4. Gunakan cursor pagination persis seperti yang dikembalikan dan berhenti saat cursor tidak ada.
5. Buat consumer webhook idempotent dengan menyimpan event ID sebelum acknowledge.

Request field rules

Gunakan nilai limit positif dan dibatasi, UUID valid, event type terdokumentasi, dan semua field JSON wajib. Jangan menaruh key di query string, browser bundle, screenshot, atau log.

API campaign dan lead

Ini adalah operasi campaign dan lead yang didukung dengan OAuth service account yang terikat ke workspace. Buat key di Settings -> Integrations, simpan nilainya saat ditampilkan sekali, dan jaga di server. Paket workspace harus mencakup akses API. Gunakan https://api.dureach.com untuk request berikut.

Mulai dengan request baca saja:

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

Daftar campaign mengembalikan items dan mungkin menyertakan next_starting_after. Kirim cursor itu tanpa perubahan pada request berikutnya. Batas maksimum limit adalah 100. Gunakan UUID dari response untuk membaca atau memperbarui campaign.

Untuk menambahkan lead, kirim JSON berikut ke POST /api/v2/lead/add:

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

Cari lead dengan GET /api/v2/lead/get?email=jane%40example.com&campaign_id=CAMPAIGN_UUID. Untuk mengubah statusnya, kirim campaign_id, email, dan new_status ke POST /api/v2/lead/update/status. Pembuatan dan pembaruan campaign memakai JSON; lihat OpenAPI schema untuk field jadwal dan sequence yang wajib.

Key terikat pada workspace pembuatnya. X-Workspace-ID yang berbeda ditolak. Key yang hilang atau tidak valid menghasilkan 401; scope yang kurang atau workspace yang berbeda menghasilkan 403. Tangani kesalahan validasi dan batas request secara terpisah. Jangan taruh key di URL, browser bundle, tangkapan layar, atau log.

Kontrak OpenAPI menjelaskan field request, response, dan bearer auth untuk tujuh operasi ini.