API לשותפים

API שרת-לשרת לשותפים: הנפיקו מפתח, קראו את הגדרות החנות ואת המיקומים, צרו לקוחות, העניקו מסלולים ונהלו קישורי מינוי מהאתר או מבוט הטלגרם שלכם.

API לשותפים מאפשר לבנות אתר משלכם, לוח בקרה משלכם או בוט טלגרם מעל CreateYourVPN.

ה-API מכסה לקוחות, מינויים, מסלולים והגדרות החנות. תשתית כמו שרתים, צמתים, פאנלים ופרטי גישה ל-SSH נמצאת מחוץ לחוזה הציבורי.

שרת-לשרת בלבד. שמרו את מפתחות ה-API בשרת שלכם ואל תכללו אותם בקוד ה-frontend. בקשות עם כותרות של דפדפן נדחות עם 403 browser_forbidden.

קבלת מפתח

פתחו את לוח הבקרה ← תפריט החשבון ← "API", הלשונית "מפתחות".

תנו למפתח שם (בוט טלגרם, דף נחיתה) ובחרו רק את ההרשאות שהוא צריך.

לחצו "הנפק מפתח" והעתיקו את הערך המלא. הסוד מוצג פעם אחת בלבד, כי נשמר רק ה-hash שלו.

לכל שותף יכולים להיות עד 5 מפתחות פעילים. כדי להחליף מפתח, הנפיקו מפתח חדש, עדכנו את האינטגרציה ואז בטלו את הישן.

אימות

שלחו את המפתח כטוקן bearer:

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

גם X-API-Key: cyv_live_… עובד, למקרים שבהם Authorization תפוס על ידי פרוקסי.

מפתח נראה כך: cyv_live_<key_id>_<secret>. החצי הראשון (key_id) ציבורי: זה מה שרואים בלוח הבקרה, ואפשר למסור אותו לתמיכה בבטחה. החצי השני הוא הסוד.

הרשאות (scopes)

הרשאה	מה היא מתירה
`config:read`	לקרוא את הגדרות החנות, המסלולים, המיקומים ו-`/me`.
`users:read`	לקרוא לקוחות, את המינויים שלהם ואת התעבורה.
`users:write`	ליצור לקוחות, להעניק מסלולים, לאפס קישורי מינוי ולמחוק לקוחות.

config:read מספיק לאינטגרציות שרק קוראות נתוני חנות. הוסיפו users:read או users:write רק כשהאינטגרציה צריכה את פעולות הלקוחות המתאימות.

החוזה המלא והניתן להרצה נמצא באוסף Postman הציבורי. הוא מכיל את כל נקודות הקצה, ההרשאות, הפרמטרים, גופי הבקשות, דוגמאות התשובות וקודי השגיאה היציבים. האוסף נוצר מחוזה ה-backend והוא המקור העדכני לסכמות של בקשות ותשובות.

פתיחת אוסף Postman הציבורי

עיינו בכל נקודות הקצה והעתיקו את האוסף ל-workspace שלכם.

מגבלות קצב

המגבלות נספרות בנפרד לכל מפתח, בלי קשר לכתובת ה-IP של הבקשה.

120 בקשות בדקה לכל מפתח בסך הכול.
10 בקשות בדקה עבור GET /users בפרט.

ל-GET /users יש מגבלה נפרדת כי כל בקשה טוענת את רשימת הלקוחות המלאה. לבדיקות שוטפות השתמשו ב-GET /users/{id} או בחיפוש לפי externalId.

דפוס גישה מומלץ. שמרו את מזהה הלקוח ב-CreateYourVPN שמוחזר ביצירה והשתמשו ב-GET /users/{id} לשליפות הבאות. אפשר לקשר אותו למזהה שלכם דרך externalId.

אידמפוטנטיות

שלוש פעולות דורשות את הכותרת Idempotency-Key: הענקת מסלול, איפוס קישור מינוי ומחיקת לקוח.

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

חזרה על בקשה עם אותו מפתח בתוך 24 שעות מחזירה את התשובה השמורה במקום להריץ את הפעולה שוב. כך נמנעים שינויים כפולים כשאינטגרציה מנסה שוב אחרי timeout.

צרו מפתח אחד לכל אירוע עסקי (למשל תשלום אחד או פעולה אחת) והשתמשו בו בכל הניסיונות החוזרים של אותו אירוע.

אם הניסיון הראשון עדיין רץ, או שהתוצאה שלו לא ידועה זמנית, ה-API מחזיר 409 conflict בלי לבצע את הפעולה שוב. לפני שמחליטים לנסות שוב, בדקו את המצב הנוכחי של הלקוח.

השתמשו באוסף Postman הציבורי שלמעלה כמקור האמת לסכמות של בקשות ותשובות.