API Mitra

API server-ke-server untuk mitra: terbitkan kunci, baca konfigurasi etalase dan lokasi, buat pelanggan, berikan paket, dan kelola tautan langganan dari situs atau bot Telegram Anda sendiri.

API Mitra memungkinkan Anda membangun situs sendiri, dasbor sendiri, atau bot Telegram di atas CreateYourVPN.

API mencakup pelanggan, langganan, paket, dan konfigurasi etalase. Infrastruktur seperti server, node, panel, dan kredensial SSH berada di luar kontrak publik.

Hanya server-ke-server. Simpan kunci API di server Anda dan jangan sertakan di kode frontend. Permintaan dengan header browser ditolak dengan 403 browser_forbidden.

Mendapatkan kunci

Buka dasbor → Menu akun → "API", tab "Kunci".

Beri nama kunci (bot Telegram, landing page) dan pilih hanya izin yang dibutuhkannya.

Pilih "Terbitkan kunci" dan salin nilainya secara utuh. Rahasianya hanya ditampilkan sekali karena yang disimpan hanya hash-nya.

Setiap mitra dapat memiliki hingga 5 kunci aktif. Untuk merotasi kunci, terbitkan kunci baru, perbarui integrasi, lalu cabut kunci lama.

Autentikasi

Kirim kunci sebagai bearer token:

curl https://api.createyourvpn.com/api/v1/partner-api/me \
  -H "Authorization: Bearer cyv_live_<key_id>_<secret>"

X-API-Key: cyv_live_… juga bisa dipakai, untuk kasus ketika Authorization sudah dipakai oleh proxy.

Kunci berbentuk cyv_live_<key_id>_<secret>. Bagian pertama (key_id) bersifat publik: itulah yang Anda lihat di dasbor dan aman disebutkan ke tim dukungan. Bagian kedua adalah rahasianya.

Izin (scopes)

Izin	Yang diizinkan
`config:read`	Membaca konfigurasi etalase, paket, lokasi, dan `/me`.
`users:read`	Membaca pelanggan, langganan, dan trafik mereka.
`users:write`	Membuat pelanggan, memberikan paket, mereset tautan langganan, menghapus pelanggan.

config:read sudah cukup untuk integrasi yang hanya membaca data etalase. Tambahkan users:read atau users:write hanya jika integrasi membutuhkan operasi pelanggan yang sesuai.

Kontrak lengkap yang bisa langsung dijalankan ada di koleksi Postman publik. Koleksi ini memuat setiap endpoint, izin, parameter, body permintaan, contoh respons, dan kode kesalahan yang stabil. Koleksi dibuat dari kontrak backend dan menjadi sumber terkini untuk skema permintaan dan respons.

Buka koleksi Postman publik

Jelajahi setiap endpoint dan salin koleksi ke workspace Anda.

Batas laju

Batas dihitung terpisah untuk setiap kunci, tidak bergantung pada alamat IP permintaan.

120 permintaan/menit per kunci secara keseluruhan.
10 permintaan/menit khusus untuk GET /users.

GET /users punya batas tersendiri karena setiap permintaan memuat seluruh daftar pelanggan. Untuk pengecekan rutin, gunakan GET /users/{id} atau cari dengan externalId.

Pola akses yang disarankan. Simpan ID pelanggan CreateYourVPN yang dikembalikan saat pembuatan dan gunakan GET /users/{id} untuk pencarian berikutnya. Anda dapat mengaitkannya dengan pengenal Anda sendiri melalui externalId.

Idempotensi

Tiga operasi memerlukan header Idempotency-Key: memberikan paket, mereset tautan langganan, dan menghapus pelanggan.

curl -X POST .../users/u_9f3a…/grant \
  -H "Authorization: Bearer $CYV_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"tariffId":"monthly"}'

Mengulang permintaan dengan kunci yang sama dalam 24 jam mengembalikan respons yang tersimpan alih-alih menjalankan operasi lagi. Ini mencegah perubahan ganda ketika integrasi mencoba ulang setelah timeout.

Buat satu kunci untuk setiap peristiwa bisnis (misalnya satu pembayaran atau satu tindakan) dan gunakan kembali untuk setiap percobaan ulang peristiwa tersebut.

Jika percobaan pertama masih berjalan, atau hasilnya untuk sementara belum diketahui, API mengembalikan 409 conflict tanpa menjalankan operasi lagi. Periksa status pelanggan saat ini sebelum memutuskan untuk mencoba ulang.

Gunakan koleksi Postman publik di atas sebagai sumber acuan untuk skema permintaan dan respons.