Alur Kerja Shortlink
- Pengguna membuat shortcode, misalnya promo123, di dashboard Qivzo
- Untuk shortcode tersebut disiapkan beberapa slot tujuan:
- url utama - tujuan utama (wajib diisi)
- url cadangan - tujuan alternatif
- url perayap - tujuan khusus perayap / crawler
- url seluler - tujuan pengunjung seluler / mobile
- url desktop - tujuan pengunjung desktop
- Berdasarkan pengaturan, Qivzo memilih URL mana yang dipakai untuk klik tersebut, lalu melakukan redirect secara otomatis.
- Jika suatu slot dikosongkan, sistem menggunakan fallback sesuai prioritas yang sudah ditentukan (misalnya kembali ke url utama).
API Qivzo: Gambaran Umum
Selain lewat dashboard, shortlink dapat diatur secara otomatis melalui API. API ini cocok diintegrasikan dengan bot Telegram, panel internal, atau skrip otomatis lainnya.
Endpoint utama:
POST https://api.qivzo.com
Format respon: selalu JSON dengan struktur dasar:
{
"error": 0,
"message": "OK"
}
- error = 0 -> permintaan berhasil.
- error ≠ 0 -> permintaan gagal. Nilainya sama dengan HTTP status (400, 401, 403, 404, dll).
Autentikasi: API Token
Setiap pengguna memiliki API Token yang bisa dilihat di halaman profil Qivzo.
- Bentuk token: selalu diawali qo_, misalnya: qo_r9FhK2x...
- Token ini digunakan untuk menghubungkan request API dengan akun Qivzo yang benar.
- Token bersifat rahasia dan tidak boleh dipublikasikan ke pihak lain.
Pada setiap permintaan ke API, kirim token di field:
token = token_milik_anda
Parameter Dasar API
Setiap permintaan ke API menggunakan parameter dasar berikut:
- token
API Token pengguna, wajib dikirim.
- action
Jenis operasi yang ingin dilakukan. Nilai yang didukung:
- update - mengubah tujuan shortlink.
- delete - menghapus shortlink.
- shortcode
Kode pendek dari shortlink yang ingin diubah atau dihapus.
Contoh: promo123, aff01, linkabc.
Aksi: UPDATE Shortlink
1. Update Satu Target (Single Target)
Digunakan jika hanya ingin mengubah satu jenis tujuan (misalnya hanya url utama atau hanya url seluler).
Parameter tambahan:
- target
Salah satu dari:
- utama
- cadangan
- perayap
- seluler
- desktop
- Value
URL baru untuk target tersebut (wajib diisi dan tidak boleh kosong).
Contoh skenario:
Mengubah tujuan utama (url utama) untuk shortcode promo123 menjadi example.com. Field yang dikirim:
- token = API Token
- action = update
- shortcode = promo123
- target = utama
- value = example.com
Contoh (untuk Linux/macOS):
curl -X POST https://api.qivzo.com \
-d "token=qo_xxxxxxxxxxxxx" \
-d "action=update" \
-d "shortcode=promo123" \
-d "target=utama" \
-d "value=example.com"
Contoh respon sukses:
{
"error": 0,
"message": "OK",
"shortcode": "promo123",
"action": "update",
"target": "utama"
}
2. Update Banyak Target Sekaligus (target=all)
Digunakan jika ingin mengatur beberapa tujuan sekaligus dalam satu permintaan API.
Parameter tambahan:
- target = all
- values[] (array, index 0-4)
Mapping index menjadi kolom:
- values[0] → utama (wajib diisi)
- values[1] → cadangan
- values[2] → perayap
- values[3] → seluler
- values[4] → desktop
NB: Jika values[1] hingga values[4] kosong → kolom tersebut akan dikosongkan di database.
Contoh skenario:
Untuk shortcode promo123, pengaturan berikut ingin dibuat:
- utama → a.com
- cadangan → b.com
- perayap → dikosongkan
- seluler → m.com
- desktop → d.com
Field yang dikirim:
- token = API Token
- action = update
- shortcode = promo123
- target = all
- values[0] = a.com
- values[1] = b.com
- values[2] = '' (kosong)
- values[3] = m.com
- values[4] = d.com
Contoh (untuk Linux/macOS):
curl -X POST https://api.qivzo.com \
-d "token=qo_xxxxxxxxxxxxxx" \
-d "action=update" \
-d "shortcode=promo123" \
-d "target=all" \
-d "values[0]=a.com" \
-d "values[1]=b.com" \
-d "values[2]=" \
-d "values[3]=m.com" \
-d "values[4]=d.com"
Contoh respon sukses:
{
"error": 0,
"message": "OK",
"shortcode": "promo123",
"action": "update",
"target": "all"
}
Aksi: DELETE Shortlink
Mode ini digunakan untuk menghapus satu shortcode yang dimiliki oleh API Token tersebut.
Parameter:
- token = API Token
- action = delete
- shortcode = kode shortlink yang ingin dihapus.
Jika permintaan berhasil, shortcode akan dihapus dari database dan tidak bisa lagi diakses.
Contoh (untuk Linux/macOS):
curl -X POST https://api.qivzo.com \
-d "token=qo_xxxxxxxxxxxxx" \
-d "action=delete" \
-d "shortcode=promo123"
Contoh respon sukses:
{
"error": 0,
"message": "OK",
"shortcode": "promo123",
"action": "delete"
}
Contoh Alur Penggunaan dari Bot
Saat diintegrasikan dengan bot (misalnya Telegram), alur kerjanya kurang lebih seperti ini:
- Pengguna mengetik perintah di bot, misalnya: setdefault promo123 a.co
- Bot membaca perintah, kemudian membentuk permintaan POST ke API Qivzo dengan field:
- token → API Token milik pengguna tersebut.
- action → update
- shortcode → promo123
- target → utama
- value → a.co
- Bot mengirim permintaan ke https://api.qivzo.com.
- Bot membaca respon JSON:
- Jika error = 0 → bot mengirim pesan ke user: “Berhasil mengubah URL utama untuk promo123.”
- Jika error ≠ 0 → bot mengirim pesan ke user sesuai message dari API (misalnya: “Shortcode tidak ditemukan”, “Token salah”, dll).
Dengan cara yang sama, bot dapat:
- Mengatur semua target sekaligus menggunakan target=all dan values[]
- Menghapus shortlink menggunakan action=delete