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.
- Buka Settings > API (di bawah Developers).
- Di bawah Personal access tokens, klik Create personal access token. Dialognya bertuliskan „Generate a token to authenticate API requests.”
- Beri Name yang mudah Anda kenali nanti, misalnya „Data warehouse”.
- 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.
- Klik Save. Anda akan melihat „Your access token has been created”.
- 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.
- 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 kampanyeread:lists(View lists): menampilkan daftar dan membaca daftar leadread:leads(View leads): membaca leadwrite:leads(Write leads): membuat, memperbarui, dan menghapus lead dalam daftarread:placements(View placements): membaca penempatanwrite:placements(Write placements): membuat, memperbarui, dan menghapus penempatanread:products(View products): membaca produkwrite: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 tokenGET /accounts: akun yang dapat Anda akses. Gunakan id akun pada panggilan lainnya.GET /accounts/{account}/campaignsdan/campaigns/{campaign}: kampanye AndaGET /accounts/{account}/campaigns/{campaign}/leads: lead sebuah kampanye, dari yang terbaru, beserta field-nya, persetujuan yang diterima, serta hadiah dan kodenya untuk pemenangGET /accounts/{account}/listsdan/lists/{list}: daftar lead Anda/accounts/{account}/lists/{list}/leads: lead sebuah daftar.GETuntuk membaca,POSTuntuk membuat,PUTuntuk memperbarui, danDELETEuntuk menghapus. Sebuah lead memilikiemail,phone_number, dancustom_tokenopsional./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.
- Buka Settings > API. Di bawah My apps, klik Create app („Register an OAuth application for the API.”).
- Isi Application name (pengguna melihatnya saat menyetujui aplikasi Anda) dan Redirect URI (alamat tujuan pengguna setelah menyetujui).
- Klik Save. Anda akan melihat „Your app has been created!” beserta Client ID dan Client secret.
- 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.