Cara Memakai Kunci API PterokuDesu: Membuat, Mencoba, dan Mengamankannya

Daftar isi

Kunci API membuat bot, situs toko, atau skripmu bisa bicara langsung dengan akun PterokuDesu-mu tanpa kamu klik-klik manual: mengecek server, membeli, memperpanjang, sampai menerima kabar lewat webhook. Artikel ini mengajarkan dari nol cara membuat kunci API yang aman, mencobanya dengan satu perintah, dan menjaganya supaya tidak bocor.

Kamu perlu akun member PterokuDesu. Admin bisa membatasi kunci dengan izin tulis (beli, perpanjang, top up) hanya untuk reseller. Kalau opsi tulis tidak bisa kamu pilih di formulir, berarti pembatasan itu sedang berlaku. Soal reseller ada di Cara jadi reseller.

Apa itu kunci API?

Kunci API adalah kata sandi khusus untuk program, bukan untuk manusia. Bentuknya seperti pdk_a1b2c3d4_ diikuti 40 karakter acak. Program mengirim kunci itu di setiap permintaan, lalu server memeriksa kunci dan izinnya sebelum menjawab. Kunci yang bocor sama bahayanya dengan password bocor, jadi baca juga bagian keamanan di bawah.

Beberapa hal tentang kunci:

Kunci lengkap hanya tampil sekali, saat dibuat. Yang kami simpan hanyalah versi hash-nya, jadi kami pun tidak bisa menampilkannya lagi.
Satu akun bisa punya sampai 10 kunci aktif. Buat kunci terpisah untuk tiap aplikasi, supaya kalau satu bocor kamu tinggal mencabut satu.
Tiap kunci punya izin, masa berlaku, dan bisa dibatasi ke alamat IP tertentu.

Langkah membuat kunci API

Masuk ke member area, lalu buka menu Pengembang, kemudian Kunci API.
Ketuk tombol Buat kunci.
Isi Nama kunci, 2 sampai 40 karakter. Pakai nama yang menjelaskan fungsinya, misalnya Bot Discord atau Toko Web.
Atur Izin akses (dijelaskan di bagian berikutnya).
Pilih Masa berlaku: 30 hari, 90 hari, 1 tahun, tanpa kedaluwarsa, atau Kustom untuk tanggal tertentu. Untuk kunci yang dipakai di server produksi, pilih masa berlaku yang tidak terlalu panjang lalu ganti kunci secara berkala.
Isi IP yang diizinkan kalau aplikasimu berjalan di server dengan IP tetap. Satu alamat per baris, boleh dalam bentuk CIDR seperti 198.51.100.0/24. Kosong berarti semua alamat boleh.
Kalau kunci punya izin beli, isi Batas belanja harian (opsional). Nilainya antara Rp10.000 dan Rp50.000.000 per hari (WIB). Kosong berarti tanpa batas. Sangat disarankan mengisinya, supaya kalau kunci disalahgunakan, kerugiannya ada batasnya.
Simpan. Kunci lengkap tampil di layar dengan peringatan. Salin sekarang dan simpan di tempat aman. Kalau halamannya tertutup, kunci tidak bisa dilihat lagi dan kamu harus membuat yang baru.

Memilih izin akses

Izin menentukan apa yang boleh dilakukan kunci. Prinsipnya: beri izin sekecil mungkin. Bot yang hanya menampilkan daftar server tidak butuh izin beli.

Di formulir, tiap sumber daya punya pilihan Tidak, Baca, atau Tulis. Memilih Tulis otomatis ikut memberi Baca. Ada juga templat cepat: Tanpa akses, Baca semua, dan Baca dan tulis semua.

Sumber daya	Baca	Tulis
Profil akun	Nama, username, email	tidak ada
Server	Daftar dan detail server	Beli, perpanjang, atur perpanjang otomatis
Transaksi	Riwayat dan detail transaksi	tidak ada
Dompet	Saldo, koin, mutasi	Membuat tagihan top up
Katalog	Paket, lokasi, metode pembayaran	tidak ada
Aktivitas	Catatan aktivitas akun	tidak ada
Referral	Kode, statistik, daftar undangan	tidak ada
Notifikasi	Daftar dan isi notifikasi	Tandai sudah dibaca
Akun panel (khusus reseller)	Daftar dan detail akun pelanggan	Buat akun pelanggan, reset password

Izin untuk beli dan perpanjang server memakai saldo dan koin di dompetmu, ditambah metode bayar lain seperti di web. Baca juga Metode pembayaran, kode promo, dan cara bayar.

Mencoba kunci pertama kali

Dokumentasi lengkap endpoint ada di halaman Dokumentasi API. Di bagian Mulai tertera alamat dasar API. Contoh berikut memakai pterokudesu.com. Kalau alamat dasar di dokumentasi berbeda, pakai yang di dokumentasi.

Buka terminal dan jalankan perintah ini (ganti KUNCIMU dengan kunci yang kamu salin):

Terminal

curl "https://pterokudesu.com/api/v1/me" \
  -H "Authorization: Bearer KUNCIMU"

Kalau berhasil, kamu mendapat balasan JSON berisi data akunmu di dalam field data. Kunci harus dikirim di header Authorization dengan awalan Bearer (ada spasi setelahnya).

Kalau gagal, balasannya berupa JSON dengan error.kode dan error.pesan. Yang paling sering:

Status	Kode	Artinya dan solusinya
401	`kunci_tidak_valid`, `kunci_kedaluwarsa`	Kunci salah ketik, sudah kedaluwarsa, atau sudah dicabut. Periksa penulisannya atau buat kunci baru. Salah kunci berkali-kali dibatasi per alamat
403	`izin_kurang`	Kunci tidak punya izin untuk endpoint itu. Ubah izin kunci atau buat kunci baru
403	`ip_ditolak`	IP server tidak ada di daftar IP yang diizinkan. Tambahkan IP-nya di pengaturan kunci
403	`batas_harian_terlampaui`	Total belanja hari ini sudah melewati batas harian kunci. Tunggu besok (WIB) atau naikkan batasnya
402	`saldo_kurang`	Saldo dompet tidak cukup untuk membayar. Top up dulu
429	`terlalu_banyak_permintaan`	Kena batas laju, sekitar 60 permintaan per menit per kunci. Kurangi frekuensi dan simpan hasil yang jarang berubah

Endpoint tulis: Idempotency-Key

Semua permintaan yang mengubah uang (beli, perpanjang, top up, batalkan) wajib membawa header Idempotency-Key berisi 8 sampai 64 karakter huruf, angka, -, atau _. Gunanya mencegah pesanan ganda kalau koneksimu putus lalu program mengulang permintaan.

Terminal

curl -X POST "https://pterokudesu.com/api/v1/servers" \
  -H "Authorization: Bearer KUNCIMU" \
  -H "Idempotency-Key: pesanan-10293" \
  -H "Content-Type: application/json" \
  -d '{ "plan_id": "plan_abc", "panel_type": "public", "server_name": "Bot Discord", "payment": { "method": "saldo" } }'

Aturannya:

Satu pesanan, satu kunci unik. Kalau permintaan putus, kirim ulang dengan kunci yang sama, jangan buat kunci baru.
Permintaan yang diulang mengembalikan hasil semula, tanpa membuat pesanan baru. Balasannya membawa header Idempotent-Replay: true.
Kunci yang sama dengan isi permintaan berbeda ditolak (422).
Kalau permintaan pertama masih diproses, ulangannya dijawab 409. Tunggu sebentar lalu coba lagi.
Tanpa header ini, permintaan ditolak (400).

Nilai plan_id dan panel_type diambil dari endpoint katalog (GET /api/v1/plans dan GET /api/v1/panel-types). Jangan menebaknya.

Alur reseller lewat API (ringkas)

Untuk reseller yang menjual ke pelanggan sendiri, urutan umumnya:

Buat kunci dengan izin akun panel, katalog, server, dan transaksi, lalu isi IP server aplikasimu dan batas belanja harian.
Ambil katalog paket dan lokasi, simpan beberapa menit supaya tidak membebani permintaan.
Buat akun pelanggan, simpan id-nya di datamu. Konsepnya ada di Multi akun panel.
Hitung biaya sebelum membayar lewat daftar metode pembayaran.
Beli server dengan Idempotency-Key unik.
Pantau sampai selesai lewat webhook atau dengan membaca status transaksi.
Perpanjang sebelum habis, atau aktifkan perpanjang otomatis dengan saldo.

Contoh perintah lengkap tiap langkah ada di bagian Alur integrasi reseller pada dokumentasi.

Webhook: terima kabar tanpa polling

Webhook membuat PterokuDesu mengirim pesan ke alamat aplikasimu saat ada kejadian, misalnya server siap atau pembayaran kedaluwarsa. Kamu mengatur webhook di menu Pengembang > Webhook.

Alamat webhook harus HTTPS dengan port 443. Alamat IP langsung dan alamat lokal ditolak.
Setiap pengiriman ditandatangani, jadi aplikasimu bisa memastikan pesannya benar-benar dari PterokuDesu. Cara memverifikasi tanda tangan ada di dokumentasi.
Pengiriman yang gagal dicoba ulang beberapa kali. Webhook yang gagal terus-menerus dimatikan otomatis.

Menjaga kunci tetap aman

Jangan taruh kunci di dalam kode yang diunggah ke GitHub atau dibagikan ke orang lain. Simpan di file .env. Panduannya ada di Cara menyimpan token bot dan password dengan aman pakai file .env.
Pakai IP yang diizinkan kalau server aplikasimu punya IP tetap.
Pakai izin sekecil mungkin dan batas belanja harian untuk kunci yang boleh membeli.
Pasang masa berlaku dan ganti kunci berkala.
Kalau curiga bocor, cabut kunci itu dari halaman Kunci API lalu buat yang baru. Kunci yang dicabut langsung berhenti bekerja.
Pantau kolom Terakhir dipakai dan log pemakaian di halaman detail kunci. Log mencatat metode, jalur, status, dan IP setiap permintaan selama sekitar 30 hari. Kalau ada pemakaian yang bukan dari aplikasimu, cabut kuncinya segera.

Lihat juga Keamanan akun dan server panel untuk kebiasaan keamanan lain.

Apakah artikel ini membantu?