# התחלה מהירה: מינוי ראשון בסביבת הבדיקות

האינדקס המלא של התיעוד: https://sublly.dev/llms.txt

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

> **מעדיפים שה-AI יעשה את זה?** מדביקים לו הוראה אחת, והוא עובר על הצעדים האלה בשבילכם. [חיבור עם AI](/docs/ai)

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

## 1. חשבון ומפתח בדיקות

פותחים חשבון ב-[לוח הבקרה](https://app.sublly.dev/app/signup), עם אימייל וקוד. בלוח הבקרה, ב"מפתחים › מפתחות API", יוצרים מפתח לאפליקציה. המפתח מוצג פעם אחת: שומרים אותו בקובץ הסביבה של השרת.

```bash .env
SUBLY_API_KEY=sk_test_...
SUBLY_BASE_URL=https://app.sublly.dev
```

המפתח סודי. הוא לא נכנס לקוד שרץ בדפדפן, ולא לקוד שעולה ל-Git.

## 2. תוכנית מחיר

יוצרים את התוכנית פעם אחת, ושומרים את המזהה שלה בהגדרות האפליקציה. סכומים הם מספר שלם באגורות: 9900 הם 99.00 ₪.

```bash curl
curl -X POST https://app.sublly.dev/v1/plans \
  -H "Authorization: Bearer $SUBLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Pro", "price_agorot": 9900, "interval": "month", "trial_days": 14}'
```

התשובה הצפויה: `201`, עם התוכנית ומזהה שמתחיל ב-`plan_`. את `trial_days` אפשר להשמיט אם אין תקופת ניסיון.

## 3. לקוח, בכל כניסה לאפליקציה

כשמשתמש נכנס לאפליקציה, יוצרים לו לקוח. אפשר לחזור על הקריאה בכל כניסה: היא לא יוצרת כפילויות. מכאן והלאה אפשר להשתמש במזהה המשתמש של האפליקציה בכל מקום שמבקש `customer_id`.

```bash curl
curl -X POST https://app.sublly.dev/v1/customers \
  -H "Authorization: Bearer $SUBLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_id": "user_42", "email": "dana@example.com"}'
```

התשובה הצפויה: הלקוח, עם מזהה שמתחיל ב-`cus_`.

## 4. כפתור הרשמה

הכפתור "הרשמה" באפליקציה פונה לשרת שלכם, והשרת יוצר מינוי ומעביר את המשתמש לכתובת שחוזרת.

```bash curl
curl -X POST https://app.sublly.dev/v1/subscriptions \
  -H "Authorization: Bearer $SUBLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"customer_id": "user_42", "plan_id": "plan_...", "success_url": "https://your.app/billing/done", "cancel_url": "https://your.app/pricing"}'
```

התשובה הצפויה: `{"url": "..."}`. זה דף התשלום, במיתוג שלכם: סיכום עם התנאים, טופס הכרטיס של חברת הסליקה, ותוצאה מאומתת. לא צריך לבנות דף תשלום משלכם. הקישור תקף 24 שעות.

בסביבת הבדיקות דף התשלום מקבל כרטיסי בדיקה בלבד:

| מספר הכרטיס | מה קורה |
| --- | --- |
| `4242 4242 4242 4242` | התשלום עובר |
| `4000 0000 0000 0002` | הכרטיס מסורב |
| `4000 0000 0000 0077` | התשלום עובר אחרי המתנה |
| `4000 0000 0000 0341` | התשלום עובר, והחיוב הבא נכשל |

**אל תסמנו את המשתמש כמנוי בדף `success_url`**: הוא רק קורא מחדש את מצב הגישה (צעד 5).

## 5. בדיקת גישה לפני כל יכולת בתשלום

לפני כל יכולת בתשלום, השרת שואל אם למשתמש יש גישה.

```bash curl
curl https://app.sublly.dev/v1/customers/user_42/access \
  -H "Authorization: Bearer $SUBLY_API_KEY"
```

```json התשובה הצפויה
{ "has_access": true, "status": "active", "current_period_end": "2026-12-22T10:00:00.000Z", "cancel_at_period_end": false }
```

מינוי שהחידוש שלו נכשל עובר ל-`past_due`, והגישה נשארת בזמן הניסיונות החוזרים (אחרי 1, 3 ו-5 ימים). אחרי הניסיון האחרון המינוי מתבטל.

**ראיתם את המינוי בלוח הבקרה? זה עובד.** [ללוח הבקרה](https://app.sublly.dev/app/)

## מה הלאה

- **אירועים:** כדי שהאפליקציה תדע מיד על כל שינוי במינוי, מוסיפים נקודת קצה ב"מפתחים › Webhooks" בלוח הבקרה. הפירוט המלא, כולל אימות החתימה, ב-[llms.txt](/llms.txt).
- **האזור האישי:** קישור "ניהול המינוי" באפליקציה, שמוביל את הלקוח להחלפת כרטיס, לחשבוניות ולביטול.
- **מעבר לאמת:** כשהכול עובד, מפעילים את החשבון בלוח הבקרה: פרטי העסק, המסוף בפלאקארד וחשבון ב-BillOS. אחרי ההפעלה יוצרים מפתח לאמת ומעדכנים את מזהי התוכניות, כי הם שונים בין הסביבות.
