API Rakan Kongsi
API pelayan-ke-pelayan untuk rakan kongsi: keluarkan kunci, baca konfigurasi storefront dan lokasi, cipta pelanggan, berikan pelan dan urus pautan langganan daripada laman atau bot Telegram anda sendiri.
API Rakan Kongsi membolehkan anda membina laman anda sendiri, papan pemuka anda sendiri atau bot Telegram di atas CreateYourVPN.
API ini meliputi pelanggan, langganan, pelan dan konfigurasi storefront. Infrastruktur seperti pelayan, nod, panel dan kelayakan SSH berada di luar kontrak awam.
Hanya untuk komunikasi pelayan-ke-pelayan. Simpan kunci API pada pelayan anda dan jangan masukkan kunci itu ke dalam kod frontend. Permintaan dengan pengepala pelayar ditolak dengan 403 browser_forbidden.
Mendapatkan kunci
Buka papan pemuka → Menu akaun → "API", tab "Kunci".
Beri kunci itu nama (bot Telegram, halaman pendaratan) dan pilih hanya kebenaran yang diperlukannya.
Pilih "Keluarkan kunci" dan salin nilai penuhnya. Rahsia hanya dipaparkan sekali kerana hanya cincangannya yang disimpan.
Setiap rakan kongsi boleh mempunyai sehingga 5 kunci aktif. Untuk menggilir kunci, keluarkan kunci baharu, kemas kini integrasi, kemudian batalkan kunci lama.
Pengesahan
Hantar kunci sebagai token bearer:
curl https://api.createyourvpn.com/api/v1/partner-api/me \
-H "Authorization: Bearer cyv_live_<key_id>_<secret>"X-API-Key: cyv_live_… juga berfungsi, untuk klien yang Authorization-nya sudah digunakan oleh proksi.
Kunci kelihatan seperti cyv_live_<key_id>_<secret>. Separuh pertama (key_id) adalah awam: itulah yang anda lihat dalam papan pemuka, dan anda boleh menyebutnya kepada pasukan sokongan dengan selamat. Separuh kedua ialah rahsia.
Kebenaran (scopes)
| Kebenaran | Apa yang dibenarkan |
|---|---|
config:read | Membaca konfigurasi storefront, pelan, lokasi dan /me. |
users:read | Membaca pelanggan serta langganan dan trafik mereka. |
users:write | Mencipta pelanggan, memberikan pelan, menetapkan semula pautan langganan, memadam pelanggan. |
config:read sudah memadai untuk integrasi yang hanya membaca data storefront. Tambah users:read atau users:write hanya apabila integrasi memerlukan operasi pelanggan yang berkaitan.
Kontrak API dan contoh
Kontrak lengkap yang boleh dijalankan terdapat dalam koleksi Postman awam. Ia mengandungi setiap endpoint, kebenaran, parameter, body permintaan, contoh respons dan kod ralat yang stabil. Koleksi ini dijana daripada kontrak backend dan menjadi sumber terkini bagi skema permintaan dan respons.
Had kadar
Had dikira berasingan bagi setiap kunci, tanpa mengira alamat IP permintaan.
- 120 permintaan/minit bagi setiap kunci secara keseluruhan.
- 10 permintaan/minit khusus untuk
GET /users.
GET /users mempunyai had tersendiri kerana setiap permintaan memuatkan senarai pelanggan yang lengkap. Untuk semakan biasa, gunakan GET /users/{id} atau carian mengikut externalId.
Cara akses yang disyorkan. Simpan ID pelanggan CreateYourVPN yang dipulangkan semasa penciptaan dan gunakan GET /users/{id} untuk semakan seterusnya. Anda boleh mengaitkannya dengan pengecam anda sendiri melalui externalId.
Idempotensi
Tiga operasi memerlukan pengepala Idempotency-Key: memberikan pelan, menetapkan semula pautan langganan dan memadam pelanggan.
curl -X POST .../users/u_9f3a…/grant \
-H "Authorization: Bearer $CYV_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"tariffId":"monthly"}'Mengulangi permintaan dengan kunci yang sama dalam tempoh 24 jam memulangkan respons yang disimpan dan tidak menjalankan operasi sekali lagi. Ini mengelakkan perubahan berganda apabila integrasi mencuba semula selepas tamat masa.
Cipta satu kunci bagi setiap peristiwa perniagaan (contohnya satu pembayaran atau satu tindakan) dan gunakan semula kunci itu untuk setiap cubaan semula peristiwa tersebut.
Jika cubaan pertama masih berjalan, atau hasilnya buat sementara tidak diketahui, API memulangkan 409 conflict tanpa menjalankan operasi sekali lagi. Semak keadaan semasa pelanggan sebelum memutuskan sama ada untuk mencuba semula.
Gunakan koleksi Postman awam di atas sebagai rujukan utama bagi skema permintaan dan respons.
Pulihkan daripada sandaran
Dua cara untuk mengembalikan pengguna anda: pemulihan papan pemuka sekali klik yang mengimportnya semula secara idempoten, atau pemulihan manual ke Marzban kosong kerana failnya dalam format pengguna Marzban asli.
Akses kecemasan
Cara sandaran untuk menyambung apabila rangkaian menggunakan senarai dibenarkan dan sambungan utama disekat: buat panggilan video, berikan pautannya kepada kami daripada panel anda atau melalui e-mel, dan dapatkan sambungan sedia guna.