הזמנת מספרי טלפון מתוך קידומת

הזמנה מתוך קידומת

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

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

שליחת בקשת הרכישה

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

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --data-urlencode 'quantity=1' \
  --data-urlencode "price_id=$PRICE_ID" \
  --data-urlencode "channels=$CHANNELS" \
  --data-urlencode "reference=$ORDER_REFERENCE" \
  --data-urlencode "uri=$VOICE_URI" \
  "https://api.multitel.net/v3/order/$PREFIX_ID"

למעלה מוצגת שליחת טופס בשיטת POST. רכיב התיאום קורא גם אובייקט JSON כאשר Content-Type הוא application/json. שדות JSON דורסים שדות תואמים בטופס או בבקשה. השתמשו באופן עקבי בקידוד אחד; אל תשלחו ערכים סותרים בפרמטרי השאילתה ובגוף הבקשה.

הגדרות מסירה וחידוש

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

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

קריאת התוצאה המלאה

פענחו את גוף ה־JSON ובדקו את status.code ואת status.msg גם כאשר בקשת ה־HTTP מצליחה. נתיב זה כותב תגובת JSON משלו, וגם רכיב העזר המשותף לתגובות אינו ממפה בהכרח את קוד היישום לסטטוס ה־HTTP. קודי יישום עשויים להיות מספרי JSON או מחרוזות מספריות. אל תדרשו את קיומו של status.results; הוא אינו מופיע בתוצאת הזמנה רגילה.

{
  "status": {"code": "200", "msg": ""},
  "response": {
    "id": "o_fictional_example",
    "numbers": ["12025550123"],
    "price": {
      "per_minute": "0.01",
      "free_minutes": 0,
      "setup_price": "1.25",
      "monthly_price": "2.50",
      "channels": 2
    },
    "features": ["voice"],
    "needs_registration": 0,
    "restrictions": "",
    "registration_requirements": null
  }
}

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

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

רכישות חלקיות ותוצאות לא ודאיות

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

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

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

רישום והפעלה

מספר שנרכש או הוקצה עשוי עדיין לדרוש רישום או הפעלה. אם needs_registration הוא 1, בדקו את restrictions ואת registration_requirements. השדה האחרון עשוי להפנות אל v3/get_requirements עם ערכי country ו־number_type. השלימו את תהליך אימות הזהות או הכתובת הנדרש ואמתו את סטטוס המספר לפני שתסתמכו על שיחות נכנסות או הודעות.

features מתאר את היכולות המוצהרות; הוא אינו מאמת ניתוב בפועל, אישור קמפיין, מסירת SMS או קבלת פקס. בדקו את הגדרות המסירה שנשמרו ובצעו את בדיקת השירות המתאימה כשהמספר פעיל.

התראות חוזרות על הזמנות

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

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

כשלים שיש לטפל בהם