שליחת פקס

לפני השליחה

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

השתמשו בחשבון API פעיל של MultiTEL. בחשבון המבוסס על סיסמה, שלחו פרטי אימות מסוג HTTP Basic, ובחשבון המבוסס על אסימון, שלחו אסימון מסוג Bearer. הרשאות החשבון וההגבלות על כתובות רשת עדיין חלות. אין להשתמש בפרטי האימות הפנימיים של רכיב העיבוד ברקע.

העלאת המסמך

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --form-string from_number=+12125550123 \
  --form-string to_number=+12125550124 \
  --form fax_file=@./document.pdf \
  https://api.multitel.net/v3/send_fax

שדות הבקשה
שדה	חובה	משמעות
`from_number`	כן	מספר השולח שאתם מורשים להשתמש בו. השתמשו בתבנית בינלאומית שמתחילה בסימן + ובקידומת המדינה.
`to_number`	כן	מספר הפקס של הנמען, בתבנית בינלאומית.
`fax_file`	כן, בבקשה מרובת חלקים	המסמך המועלה. אפשרו ל־curl להגדיר את Content-Type ואת מפריד החלקים של הבקשה מרובת החלקים.
`webhook_url`	לא	כתובת אופציונלית להודעות חוזרות בפרוטוקול HTTP או HTTPS; עדיף להשתמש ב־HTTPS. תוכן ההודעות החוזרות וההתחייבויות למסירתן עדיין בבדיקה: תשאלו את fax_status מעת לעת כדי לפעול לפי תהליך מעקב המצב המתועד.

ניתן לשלוח גם JSON עם Content-Type: application/json, אותם שדות מספרים והשדה האופציונלי webhook_url, ובתוספת file_name וכן file_b64. השדה file_b64 מכיל את בתי המסמך בקידוד Base64 תקני לחלוטין, ללא הקידומת data:. לשדה fax_file תקין בבקשה מרובת חלקים ניתנת עדיפות. זה אינו API לאחזור קבצים מכתובות אינטרנט.

מגבלות מסמכים והגשת בקשות

היישום מקבל מסמכים בגודל של עד 15,728,640 בתים לאחר פענוח הקידוד (15 MiB), עם הסיומות pdf, tif, tiff, jpg, jpeg, png, doc, docx או txt. סיומת מותרת אינה מבטיחה שהשירות יוכל לספור את העמודים או להמיר אותם. מגבלות גודל הבקשה בתשתית עשויות להיות נמוכות יותר, וקידוד Base64 מגדיל את הבקשה.

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

שמירת מזהה המשימה

בדקו גם את תוצאת HTTP וגם את השדה status.code בתשובת JSON. שגיאות בתשובת JSON עשויות להגיע עם HTTP 200. תשובת JSON מוצלחת כוללת את status ואת response; הנתונים בדוגמאות בדויים.

{
  "status": {
    "code": 200,
    "msg": "Fax queued"
  },
  "response": {
    "job_id": "0123456789abcdef0123456789abcdef"
  }
}

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

שגיאות ובדיקות יתרה

קודי API כוללים 400 עבור שדות חסרים, כתובת לא תקינה להודעות חוזרות, מסמך שנדחה או כשל בזיהוי העמודים; 401 כאשר חסר אימות; 402 כאשר עלות הפקס המשוערת בתוספת אומדני העלות של המשימות שבתור או בשליחה עולה על היתרה הזמינה בחשבון; 429 עבור מגבלות קצב; ו־500 עבור כשל בשלב ההכנה לשליחה. קראו את status.msg לקבלת הסיבה המדויקת.

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