מחברים את המערכות האחרות שלכם ל-RushHour,
דרך אותו API שעליו פועלות האפליקציות שלנו.
ה-REST API של RushHour הוא אותו API שעליו פועלים פורטל החברה, פורטל הלקוחות ואפליקציית הנהג, והוא מתועד למפתחים ב-docs.rushhourapp.com: 508 נקודות קצה להצעות מחיר והזמנות, שיבוץ, לקוחות, חשבוניות, נהגים, מסמכים ועוד. כבר היום מערכת מחוברת נכנסת כמשתמש ייעודי של פורטל החברה, ויכולה לעשות רק את מה שהתפקידים של אותו משתמש מאפשרים. אסימוני API, שבזכותם מערכת כבר לא תצטרך להתחבר עם סיסמה, יגיעו בגרסה הבאה.
ה-API במבט אחד
זמין כבר היום
ה-API של RushHour כבר היום
REST API מעל HTTPS ששולח ומקבל JSON, בכתובת https://api.rushhourapp.com/api/v1. פורטל החברה, פורטל הלקוחות ואפליקציית הנהג משתמשים כולם באותו API, כך שהמערכות שלכם יכולות לעשות את מה שהצוות שלכם עושה על המסך, עם אותן הרשאות.
מתועד
API אחד ומתועד, אותו API שעליו פועלות האפליקציות של RushHour
תיעוד ה-API הציבורי ב-docs.rushhourapp.com/developers נוצר ישירות מה-API ומתאר את הגרסה שפועלת היום. לכל נקודת קצה מפורטים הפרמטרים, גוף הבקשה והתשובה, ובנקודות קצה שתמיד דורשות הרשאה או תפקיד מסוימים, גם אותם, בשמות שמופיעים בדף התפקידים בפורטל החברה. מדריכים נוספים מסבירים התחברות, חלוקה לעמודים וסינון, תאריכים ואזורי זמן, מגבלות קצב, ואיך לשמור מערכת אחרת מסונכרנת.
- כתובת בסיס https://api.rushhourapp.com/api/v1, עם JSON בבקשה ובתשובה
- הגרסה היא חלק מכל נתיב: v1, ו-v2 לחיפוש הגלובלי
- ההרשאה הנדרשת מצוינת בשמות ההרשאות שהמנהלים שלכם כבר מקצים
ההרשאות שלכם חלות
כל בקשה מתבצעת בשם משתמש RushHour
ה-API בודק את התפקידים וההרשאות של המשתמש בכל בקשה, בדיוק כמו פורטל החברה, ורשימות כוללות רק רשומות שהמשתמש רשאי לראות. פעולה שנדחתה מחזירה 403, בדרך כלל עם הקוד meta.missing_permission ושם ההרשאה החסרה. שינויים שנעשים דרך ה-API מופיעים תחת שם המשתמש בהגדרות > יומני פעילות וביומן הביקורת של כל הזמנה.
- אותם תפקידים, הרשאות ונראות נתונים כמו על המסך
- קוד 403 עם meta.missing_permission מציין איזו הרשאה חסרה
- השינויים נרשמים תחת שם המשתמש ביומני הפעילות ובהיסטוריית השינויים
מתחברים כבר היום
מתחברים כמשתמש ייעודי לאינטגרציה
יוצרים משתמש של פורטל החברה לכל אינטגרציה בהגדרות > משתמשים, ונותנים לו רק את התפקידים שהוא צריך. המערכת שלכם מתחברת עם POST /api/v1/Auth/Login באמצעות המייל והסיסמה של המשתמש, ומקבלת אסימון (bearer token) שנשלח בכותרת Authorization. האסימון תקף עד 30 ימים, והוא מפסיק לפעול מוקדם יותר אם הסיסמה של המשתמש שונתה או אופסה, או אם המשתמש הושבת או נמחק. אין אסימוני רענון: כשבקשה מחזירה 401, פשוט מתחברים שוב.
- משתמש אחד לכל אינטגרציה, רק עם התפקידים שהיא צריכה
- איפוס סיסמה או השבתת המשתמש מנתקים את האינטגרציה
- הקריאה GET /Permissions/CurrentRolesWithPermissions מראה מה היא רשאית לעשות
צפוי ועקבי
מבנה תשובה אחד, רשימות בעמודים ומגבלות ברורות
כמעט כל נקודת קצה עוטפת את התשובה באותו מבנה: הנתונים, סימון הצלחה, הודעות קריאות, שגיאות קריאות למכונה עם קוד כמו auth.invalid_login, ואזהרות שלא עצרו את הבקשה. רשימות מגיעות בעמודים של עד 1,000 פריטים ברוב נקודות הקצה, יחד עם הספירה הכוללת. נקודות קצה כבדות, כמו העלאת מסמכים, יכולות AI וחלק מחיפושי המפה והכתובות, מוגבלות לכל משתמש ומחזירות 429 כשמשתמש שולח יותר מדי בקשות, כך ששאר המשתמשים ממשיכים לעבוד.
- קודי שגיאה קריאים למכונה; שגיאת 500 כוללת מספר אסמכתה לפנייה לתמיכה
- חותמות זמן ב-UTC, בפורמט ISO 8601
- מגבלות 429 לכל משתמש; המספרים המדויקים לא מפורסמים
בלי webhooks
אין webhooks: במקומם, מתכון מתועד לבדיקה תקופתית
RushHour לא פונה למערכות שלכם כשרשומה משתנה, והסינון ברשימות מתבצע לפי תאריכים וסטטוסים עסקיים, לא לפי מועד העריכה האחרון. במקום זה, התיעוד למפתחים מציע מתכון שלב אחר שלב: בוחרים מרווח זמן שמתאים לרמת העדכניות הנדרשת, קוראים מחדש את כל הרשומות שעדיין יכולות להשתנות, משווים לפי מזהה, ומאטים את הקצב כשה-API מחזיר 429 או 503.
- כל כמה דקות לנתוני שיבוץ, כל שעה או כל יום לנתוני הנהלת חשבונות
- קוראים מחדש רשומות פתוחות, לא רק תאריכים אחרונים
- ב-429 וב-503 ממתינים ומנסים שוב, עם המתנה שהולכת וגדלה
מה ה-API מכסה
508 נקודות קצה ב-16 תחומים
מקובצות כמו בתיעוד ה-API הציבורי. כל נקודת קצה פועלת עם ההרשאות של המשתמש ששולח את הבקשה.
הצעות מחיר והזמנות
84 נקודות קצה. יוצרים ומעדכנים הצעות מחיר, מאשרים אותן להזמנות, עובדים עם עצירות ועיכובים, סוגרים הזמנות וקוראים את היסטוריית ההזמנה.
שיבוץ ומסלולים
31 נקודות קצה. יוצרים ומשנים מסלולים, משבצים עצירות ומוציאים אותן מהשיבוץ, מגדירים העברות ומחפשים כתובות על המפה.
לקוחות
70 נקודות קצה. חשבונות לקוח, אנשי קשר וכתובות, פניות תמיכה, הודעות ללקוחות וגישה לפורטל הלקוחות.
הנהלת חשבונות
43 נקודות קצה. מחפשים, יוצרים ומעדכנים חשבוניות, רושמים תשלומים ומשייכים אותם לחשבוניות, ומנהלים סוגי חיובים וחשבונות הפקדה.
מסמכים
44 נקודות קצה. ספריית המסמכים והקבצים המצורפים, וגם הצעות מחיר, שטרי מטען, תוויות וחשבוניות כ-PDF או כ-HTML, להורדה או לשליחה בדוא"ל.
נהגים
23 נקודות קצה. מוסיפים, מעדכנים, מזמינים, מפעילים ומשביתים נהגים, מנהלים סוגי רישיונות, וקוראים או משנים את הגדרות אפליקציית הנהג.
צי רכב
14 נקודות קצה. המשאיות שלכם והעלויות שלהן, וכלי רכב מחשבון Samsara מחובר.
מובילים חיצוניים
30 נקודות קצה. המובילים החיצוניים שאתם עובדים איתם, אנשי הקשר והפרופילים הכספיים שלהם, וסוגי המשאיות שהם מפעילים.
תמחור
23 נקודות קצה. מודלי תמחור, אזורי תמחור, סוגי משלוח ושערי חליפין למטבעות אחרים.
הוצאות
45 נקודות קצה. רושמים ומאשרים הוצאות, מסדרים אותן לפי קטגוריה וספק, מתזמנים הוצאות חוזרות ומנתחים עלויות.
תיבת דואר והתראות
48 נקודות קצה. קוראים ושולחים דוא"ל מתיבת הדואר של החברה, מתכתבים עם נהגים ועובדים עם ההתראות שבתוך המערכת.
לוח בקרה
11 נקודות קצה. הנתונים שמאחורי לוח הבקרה, ופריסות של לוח הבקרה.
הגדרות החברה
20 נקודות קצה. המיקומים שלכם, אזורי שיבוץ, ימים שאינם ימי עבודה, ותנאים והגבלות.
משתמשים ותפקידים
10 נקודות קצה. רשימת המשתמשים של פורטל החברה, הפעלה, השבתה או שליחת הזמנה מחדש, וקריאת התפקידים וההרשאות.
חשבון וחברה
6 נקודות קצה. התחברות, בדיקה מי מחובר, קריאת פרטי החברה ובדיקת גרסת ה-API.
נתוני ייחוס
6 נקודות קצה. חיפוש ארצות, מדינות, ערים ומיקודים.
נסו בעצמכם
בקשה ראשונה
מתחברים עם POST /api/v1/Auth/Login, לוקחים את האסימון מהשדה data ושולחים אותו בכותרת Authorization של כל בקשה. הקריאה הראשונה הזו מחזירה את התפקידים של המשתמש ואת ההרשאות שכל תפקיד מעניק.
היום: עם אסימון התחברות
curl "https://api.rushhourapp.com/api/v1/Permissions/CurrentRolesWithPermissions" \
-H "Authorization: Bearer YOUR_TOKEN"אסימון ההתחברות תקף עד 30 ימים. כשבקשה מחזירה 401, מתחברים שוב.
עם אסימון APIבגרסה הבאה
curl "https://api.rushhourapp.com/api/v1/App/WhoAmI" \
-H "Authorization: Bearer YOUR_API_TOKEN"אסימון API נשלח באותה כותרת Authorization. חלון יצירת אסימון ה-API מציג את קריאת הבדיקה הזו, והתשובה שלה מראה בשם מי האסימון פועל ואילו תפקידים יש לו.
תיעוד למפתחים
קראו את התיעוד לפני שאתם בונים
התיעוד ציבורי, באנגלית, בכתובת docs.rushhourapp.com/developers.
בגרסה הבאה
אסימון נפרד לכל מערכת שאתם מחברים
אסימוני API מיועדים למפתחים שלכם או לשותף האינטגרציה שלכם. הם מוכנים ויגיעו עם הגרסה הבאה של RushHour: מערכת מחוברת תשלח אז אסימון במקום להתחבר כמשתמש, לאותו API ולאותן נקודות קצה שמתוארות למעלה, מלבד פעולות החשבון והאבטחה שמפורטות בהמשך. מנהלי החברה יוצרים אסימונים בהגדרות > אסימוני API.
גישה לפי תפקיד
כל אסימון מקבל רק את התפקידים שהוא צריךבגרסה הבאה
בחלון יצירת אסימון API נותנים לאסימון שם, מוסיפים תיאור אופציונלי של מה שישתמש בו ובוחרים תפקיד אחד או יותר. האסימון יכול לעשות את מה שמשתמש עם התפקידים האלה יכול לעשות, ורק בחברה שבה נוצר. מנהל חברה יכול לבחור כל תפקיד משרדי מובנה או כל תפקיד מותאם של החברה, ושאר המשתמשים יכולים לבחור רק תפקידים שיש להם בעצמם.
- תפקיד אחד או יותר לכל אסימון, מובנים או מותאמים
- פועל רק בחברה שבה נוצר
- אזהרה כשבוחרים מנהל חברה
מוצג פעם אחת
קובעים תפוגה, ואז מעתיקים את האסימון פעם אחתבגרסה הבאה
אפשר לבחור 7, 30, 90 או 180 ימים, או שנה, וברירת המחדל היא 90 ימים; בחירה ב"ללא תפוגה" מציגה אזהרה. האסימון מוצג פעם אחת, עם כפתור להעתקה, ו-RushHour אף פעם לא שומרת את האסימון המלא, כך שאי אפשר להציג אותו שוב. באותו חלון מופיעה גם פקודת בדיקה למפתחים שלכם, והתשובה שלה מראה בשם מי האסימון פועל ואילו תפקידים יש לו.
- תפוגה של 7, 30, 90 או 180 ימים או שנה (90 כברירת מחדל), או ללא תפוגה
- מוצג פעם אחת, והאסימון המלא אף פעם לא נשמר
- פקודת בדיקה לווידוא שהאסימון עובד
כל האסימונים ברשימה
רואים בשם מי כל אסימון פועל ומתי נעשה בו שימוש אחרוןבגרסה הבאה
בהגדרות > אסימוני API מופיע כל אסימון עם התווים הראשונים שלו, התפקידים שלו, המשתמש שבשמו הוא פועל, מי יצר אותו ומתי, ומועד התפוגה שלו. בעמודה שימוש אחרון רואים בערך לפני כמה זמן נעשה שימוש באסימון, עם התאריך והשעה במעבר עכבר, ומתחת מופיעה כתובת IP משוערת. אסימונים שבוטלו נשארים ברשומות ומופיעים כשמסמנים את התיבה הצגת אסימונים שבוטלו.
- לכל אסימון: תפקידים, פועל בשם, נוצר ותפוגה
- שימוש אחרון, עם כתובת IP משוערת
- סטטוס פעיל, פג תוקף, בוטל או מושהה
ביטול או השהיה
מנתקים מערכת אחת בלי לשנות סיסמה לאף אחדבגרסה הבאה
מבטלים אסימון מהתפריט שלו, והמערכת שמשתמשת בו מפסיקה לעבוד, בעוד שהאנשים בצוות ממשיכים להתחבר כרגיל. אסימון מפסיק לפעול גם כשתוקפו פג, והוא עובר לסטטוס מושהה כל עוד המשתמש שבשמו הוא פועל מושבת, הוסר מהחברה או נותר בלי תפקידים שהאסימון יכול להשתמש בהם. כשמנהל מאפס סיסמה של משתמש אחר, האסימונים של אותו משתמש מבוטלים, ואילו כשאתם משנים את הסיסמה שלכם, האסימונים שלכם ממשיכים לפעול.
- ביטול מתפריט האסימון, אחרי אישור
- מושהה כל עוד המשתמש שלו מושבת או הוסר
- איפוס סיסמה בידי מנהל מבטל את אסימוני המשתמש
רק לאנשים מחוברים
מה אסימון לעולם לא יכול לעשותבגרסה הבאה
יש פעולות שתמיד דורשות אדם שמחובר לפורטל החברה. אסימון שמנסה לבצע אחת מהן נדחה עם 403 והקוד auth.interactive_session_required, כך שאסימון לעולם לא יכול להעניק לעצמו, או לאחרים, יותר גישה.
- להוסיף, לערוך, להשבית או למחוק משתמשים, או לשנות תפקידים והרשאות
- לשנות, לקבוע או לאפס סיסמאות
- ליצור, להציג או לבטל אסימוני API
- לשמור או לשנות מפתחות של אינטגרציות ותשלומים
- לשלוח הזמנות למשתמשים, לנהגים או למשתמשי פורטל הלקוחות, או לערוך את פרטי החברה
בשליטת המנהלים
המנהלים מחליטים מי יכול ליצור אסימוניםבגרסה הבאה
לעמוד אסימוני API יש הרשאה משלו, שיש למנהלי החברה כברירת מחדל, והם יכולים להעניק אותה לתפקידים אחרים בהגדרות > משתמשים. אסימון פועל בשם מי שיצר אותו, מוגבל לתפקידים שנבחרו עבורו, כך שלעולם אין לו יותר גישה מאשר ליוצר שלו. יצירה וביטול של אסימון נרשמים בהגדרות > יומני פעילות.
- מנהלי החברה כברירת מחדל, ותפקידים אחרים כשמקבלים הרשאה
- כל אסימון פועל בשם מי שיצר אותו, ולעולם לא עם יותר גישה
- עד 50 אסימונים פעילים לכל חברה
איפה אסימוני API עוזרים
בלי סיסמאות משותפותבגרסה הבאה
המערכת המחוברת אף פעם לא מחזיקה את המייל והסיסמה של אדם, ולכן משתמש שמשנה את הסיסמה שלו לא גורם לה להפסיק לעבוד.
רק הגישה הנדרשתבגרסה הבאה
כל אסימון מקבל את התפקידים שבחרתם ופועל בחברה אחת, כך שתהליך הפקת דוחות לא מקבל הרשאות שהוא לא משתמש בהן.
גישה שאפשר לעקוב אחריהבגרסה הבאה
כל אסימון מראה בשם מי הוא פועל, מי יצר אותו ומתי נעשה בו שימוש אחרון, וביטול אחד מפסיק אותו.
שאלות על ה-API
אפשר להתחבר ל-API של RushHour כבר היום?
כן. יוצרים משתמש ייעודי של פורטל החברה לאינטגרציה, רק עם התפקידים שהיא צריכה, מתחברים עם POST /api/v1/Auth/Login ושולחים את האסימון שמתקבל בכותרת Authorization. האסימון תקף עד 30 ימים. אסימוני API, שמאפשרים למערכת להתחבר בלי הסיסמה של משתמש, יגיעו בגרסה הבאה.
מה אינטגרציה יכולה לעשות דרך ה-API?
כל מה שהמשתמש שבשמו היא מתחברת רשאי לעשות: הצעות מחיר והזמנות, שיבוץ ומסלולים, לקוחות, חשבוניות ותשלומים, תמחור, נהגים, משאיות, מובילים חיצוניים, הוצאות, מסמכים, הודעות והגדרות החברה, ב-508 נקודות קצה מתועדות. רשימות כוללות רק רשומות שהמשתמש רשאי לראות.
האם RushHour שולחת webhooks?
לא. אין אפשרות לרשום כתובת URL ש-RushHour תפנה אליה כשהזמנה, מסלול, חשבונית או רשומה אחרת משתנים. במקום זה האינטגרציה שלכם בודקת את ה-API לפי לוח זמנים, והתיעוד למפתחים מציע מתכון מפורט לבדיקה תקופתית.
יש סביבת ניסוי (sandbox)?
לא. אין סביבת ניסוי נפרדת. אינטגרציה עובדת עם הנתונים של החברה שלכם, כמשתמש ייעודי שמוגבל לתפקידים שהוא צריך. דברו עם הצוות שלנו לפני שאתם בונים משהו שכותב נתונים בכמויות גדולות.
יש SDK או ספריית לקוח?
לא. ה-API הוא REST רגיל מעל HTTPS עם JSON, כך שכל שפת תכנות ששולחת בקשות HTTP יכולה לעבוד איתו. תיעוד ה-API מפרט לכל נקודת קצה את הפרמטרים, גוף הבקשה והתשובה.
יש מגבלות קצב?
כן, בנקודות קצה כבדות כמו העלאת מסמכים, יכולות AI וחלק מחיפושי המפה והכתובות. המגבלות נספרות לכל משתמש, ובקשה שחורגת מהמגבלה מקבלת 429 עם תשובה ריקה. המספרים המדויקים לא מפורסמים, ולכן כדאי לבנות המתנה וניסיון חוזר עם הפסקות שהולכות ומתארכות.
מתי יגיעו אסימוני API?
אסימוני API מוכנים ויגיעו עם הגרסה הבאה של RushHour. עד אז, השתמשו במשתמש ייעודי לאינטגרציה. כשתעברו לאסימון, הבקשות נשארות אותן בקשות: המערכת שולחת את אסימון ה-API באותה כותרת Authorization במקום אסימון ההתחברות. שינויים במשתמשים, בתפקידים, בסיסמאות ובאסימונים עדיין דורשים אדם שמחובר לפורטל החברה.
עמודים קשורים
הביאו את המערכת שאתם רוצים לחבר.
בהדגמה נפתח את תיעוד ה-API על הרשומות שהאינטגרציה שלכם צריכה, ונגדיר יחד אילו תפקידים צריך משתמש ייעודי לאינטגרציה, כך שתדעו מה לבנות עוד לפני שמתחילים.