רישיונות ובורר ה-license_key

רישיון (License) הוא חשבון יחיד בחברת שליחויות — פרטי הגישה וההגדרות של סוחר אחד עבור חברת שליחויות אחת (HFD, זיגזג, Cargo, איסוף עצמי וכן הלאה). חשבון סוחר יכול להחזיק כמה רישיונות. endpoints הכפופים לרישיון פועלים תמיד תחת רישיון אחד בדיוק, שנבחר בכל בקשה.

בחירת רישיון

בקשות הכפופות לרישיון בוחרות את הרישיון שלהן באמצעות שדה license_key שערכו הוא עמודת ה-key של הרישיון:

• ב-endpoints מסוג GET, העבירו אותו כפרמטר query: ?license_key=...
• ב-endpoints של כתיבה (POST/PUT/PATCH/DELETE), העבירו אותו כשדה בגוף הבקשה.

כללי הפענוח

הבורר משקף במדויק את הלוגיקה של license() ב-controller הבסיסי:

מצב	תוצאה
license_key סופק, שייך לכם, פעיל ולא פג תוקף	הרישיון הזה בשימוש.
license_key הושמט, לחשבון יש בדיוק רישיון פעיל אחד	הרישיון הזה בשימוש (ברירת מחדל).
license_key הושמט, לחשבון יש יותר מרישיון פעיל אחד	422 validation_failed — license_key נדרש.
license_key הושמט, לחשבון אין רישיון פעיל	403 forbidden.
license_key סופק אך אינו בבעלותכם (או לא נמצא)	403 forbidden.
הרישיון שנבחר אינו פעיל	403 forbidden.
הרישיון שנבחר פג תוקף	403 forbidden.

קודים והודעות מדויקים

כל השגיאות משתמשות במעטפת השגיאה הסטנדרטית.

כמה רישיונות, אף אחד לא צוין — 422, קוד validation_failed:

{
  "error": {
    "code": "validation_failed",
    "message": "You have multiple licenses — specify which one with license_key.",
    "status": 422,
    "details": {
      "license_key": [
        "The license_key field is required when the account has more than one license."
      ]
    }
  }
}

אין רישיון פעיל — 403, קוד forbidden, הודעה Your account has no active license.

license_key לא בבעלותכם / לא נמצא — 403, קוד forbidden, הודעה The requested license does not belong to you.

רישיון לא פעיל — 403, קוד forbidden, הודעה This license is inactive.

רישיון שפג תוקפו — 403, קוד forbidden, הודעה This license has expired.

גילוי הרישיונות שלכם

קראו ל-GET /account — התגובה כוללת את כל הרישיונות שהחשבון מחזיק (כל אחד עם ה-key שלו, is_active, is_expired, חברת השליחויות וההגדרות). השתמשו בערך ה-key של הרישיון כבורר license_key.