Langsung ke konten
Rex, asisten AI Anda: pekerjaan rutin beres, idenya tetap milik Anda 👉 Kenalan dengan Rex

Mulai menggunakan REST API

Buat token akses pribadi dengan scope yang tepat, atau daftarkan aplikasi OAuth, lalu baca kampanye, lead, dan daftar dari sistem Anda sendiri.

REST API Scratcher memungkinkan sistem Anda sendiri membaca kampanye, lead, dan daftar Anda, menambahkan dan memperbarui lead, serta mengelola produk dan penempatan. Artikel ini ditujukan untuk developer yang menyiapkannya.

API termasuk dalam paket yang menyertakan Webhooks & API (Basic ke atas). Pada paket lain, tombol untuk membuat token dan aplikasi terkunci.

Membuat token akses pribadi

Token akses pribadi adalah cara tercepat untuk memanggil API dari skrip dan sistem Anda sendiri.

  1. Buka Settings > API (di bawah Developers).
  2. Di bawah Personal access tokens, klik Create personal access token. Dialognya bertuliskan „Generate a token to authenticate API requests.”
  3. Beri Name yang mudah Anda kenali nanti, misalnya „Data warehouse”.
  4. Di bawah Scopes, pilih apa saja yang boleh dilakukan token tersebut (lihat di bawah). Select all memilih semua scope. Berikan token hanya akses yang benar-benar dibutuhkan.
  5. Klik Save. Anda akan melihat „Your access token has been created”.
  6. Salin token di bawah Secret. „Save the secret above, as this is the only time you will see it.” Simpan dengan aman, misalnya di pengelola kata sandi.
  7. Klik Close.

Token terikat pada pengguna Anda. Token ini dapat menjangkau setiap akun Scratcher tempat Anda menjadi anggota, dengan scope yang Anda pilih.

Scope

  • read:campaigns (View campaigns): menampilkan daftar dan membaca kampanye
  • read:lists (View lists): menampilkan daftar dan membaca daftar lead
  • read:leads (View leads): membaca lead
  • write:leads (Write leads): membuat, memperbarui, dan menghapus lead dalam daftar
  • read:placements (View placements): membaca penempatan
  • write:placements (Write placements): membuat, memperbarui, dan menghapus penempatan
  • read:products (View products): membaca produk
  • write:products (Write products): membuat, memperbarui, dan menghapus produk

Untuk membaca lead sebuah kampanye, token memerlukan read:campaigns dan read:leads sekaligus. Membuat dan mengubah penempatan juga memerlukan Embed / URL dalam paket Anda.

Mencabut token

Klik token di daftar untuk membuka Show personal access token. Di sana ditampilkan Name dan Scopes. Klik Revoke lalu konfirmasi („Are you sure you want to delete this token? This cannot be undone!”). Apa pun yang menggunakan token tersebut akan langsung berhenti berfungsi.

Mengirim permintaan

URL dasarnya adalah https://platform.scratcher.io/api/v1/. Kirim token di header Authorization, dan minta respons dalam format JSON:

curl https://platform.scratcher.io/api/v1/accounts \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Accept: application/json" 

Endpoint utama

  • GET /me: pengguna pemilik token
  • GET /accounts: akun yang dapat Anda akses. Gunakan id akun pada panggilan lainnya.
  • GET /accounts/{account}/campaigns dan /campaigns/{campaign}: kampanye Anda
  • GET /accounts/{account}/campaigns/{campaign}/leads: lead sebuah kampanye, dari yang terbaru, beserta field-nya, persetujuan yang diterima, serta hadiah dan kodenya untuk pemenang
  • GET /accounts/{account}/lists dan /lists/{list}: daftar lead Anda
  • /accounts/{account}/lists/{list}/leads: lead sebuah daftar. GET untuk membaca, POST untuk membuat, PUT untuk memperbarui, dan DELETE untuk menghapus. Sebuah lead memiliki email, phone_number, dan custom_token opsional.
  • /accounts/{account}/products: produk (GET, POST, PUT, DELETE)
  • /accounts/{account}/placements: penempatan (GET, POST, PUT, DELETE)

Daftar ditampilkan per halaman: tambahkan ?page=2 dan seterusnya. Anda hanya dapat menjangkau akun tempat Anda menjadi anggota; id akun lain akan menghasilkan error.

Batasan

Anda dapat mengirim 60 permintaan per menit per pengguna. Jika melebihi batas, API menjawab dengan status 429; tunggu sebentar lalu coba lagi.

Referensi API

Referensi lengkap, dengan semua field, filter, contoh, dan koleksi Postman, tersedia di dokumentasi referensi API. Tombol API reference di bagian atas Settings > API juga menautkan ke sana.

Membangun aplikasi dengan OAuth

Jika Anda membangun aplikasi yang dihubungkan oleh pengguna Scratcher lain ke akun mereka sendiri, daftarkan aplikasi OAuth alih-alih menggunakan token pribadi.

  1. Buka Settings > API. Di bawah My apps, klik Create app („Register an OAuth application for the API.”).
  2. Isi Application name (pengguna melihatnya saat menyetujui aplikasi Anda) dan Redirect URI (alamat tujuan pengguna setelah menyetujui).
  3. Klik Save. Anda akan melihat „Your app has been created!” beserta Client ID dan Client secret.
  4. Salin client secret sekarang: „Save the client secret above, as this is the only time you will see it.” Klik Continue.

Aplikasi Anda mengarahkan pengguna ke https://platform.scratcher.io/oauth/authorize dengan client ID, redirect URI, dan scope yang dibutuhkan. Pengguna masuk ke Scratcher dan melihat Authorization request: „This application will be able to:” diikuti daftar scope. Mereka mengklik Authorize atau Cancel. Aplikasi Anda kemudian menukar kode tersebut dengan token di https://platform.scratcher.io/oauth/token.

  • Token akses dari OAuth berlaku selama dua bulan. Refresh token berlaku selama tiga bulan; gunakan untuk mendapatkan token akses baru.
  • Untuk mengubah nama atau redirect URI, klik aplikasi di bawah My apps, ubah, lalu klik Save („Your settings have been saved”). „You cannot view your secret afterwards.”
  • Delete app menghapus aplikasi, dan koneksi setiap pengguna ke aplikasi tersebut akan berhenti berfungsi: „Are you sure you want to delete this app? This cannot be undone!”

Aplikasi yang telah Anda setujui

Authorized apps menampilkan aplikasi yang telah Anda beri akses ke akun Anda, seperti Zapier, beserta scope yang dimilikinya. Klik Revoke untuk mencabut aksesnya.

Siapa yang dapat menggunakan API?

Halaman API ditampilkan untuk pengguna dengan peran Owner, Admin, atau Manager. Token tidak pernah bisa melakukan lebih dari yang bisa dilakukan pengguna yang membuatnya.

Butuh bantuan?

Masih butuh bantuan?

Tim kami siap membantu. Jika Anda sudah menggunakan Scratcher, cara tercepat adalah lewat chat di dalam platform.

  • Chat dengan kami

    Masuk dan klik tombol chat di pojok kanan bawah. Rex langsung menjawab, dan tim kami hanya sejauh satu klik.

  • Jadwalkan pertemuan

    Panggilan video gratis 30 menit dengan tim kami: tur produk, ide kampanye, atau bantuan penyiapan.

  • Kirim email

    Kirim email ke contact@scratcher.io dan kami akan segera membalas.