מה זה API?
הגדרה לא רשמית
נתחיל במטאפורות כמו שאני אוהב, ואז נעבור להגדרה הרשמית.
API היא היכולת של מערכות לתקשר אחת עם השניה: להעביר, לעדכן ולמחוק מידע אחת מהשניה.
רגע, אבל בשביל זה יש את מערכת Make המפורסמת, לא? שעושה את הדבר הזה ללא קוד…
אז נכון, אבל יש מערכות שאין להן אפליקציה ב-MAKE והדרך לגרום להן לדבר אחת עם השניה היא בעזרת API.
הגדרה הרשמית
ראשי התיבות של API הם: Application Programming Interface.
זה בעצם ממשק תכנות יישומים המגדיר את כללי התקשורת בין מערכות שונות.
הממשק מכיל אוסף של פרוטוקולים, כלים והגדרות המאפשרים לתוכנות שונות לתקשר זו עם זו ולשתף מידע ופעולות דו כיווניות (נכון שההגדרה הלא רשמית עדיפה? 😉
בשלב הזה סיכוי טוב שעובר לכם בראש המשפט הבא:
"אוקיי, נשמע כמו משהו שדורש עבודה עם קוד, ואמרו לי שאוטומציה עסקית הוא עולם ללא קוד"...
אז בגדול קריאת API מכילה בדרך כמה שורות של טקסט "שעלולות" להיראות כמו קוד,אבל זה הרבה יותר פשוט ממה שנראה.
האמת שכדי לעבוד נכון עם API לא באמת צריך לדעת לכתוב קוד, אלא רק להבין מה התפקיד של כל מרכיב בתהליך ולהיות ממש טובים ב"העתק - הדבק".
אז יאללה בואו נכיר קצת מושגים הקשורים ל-API, ואז נעבור לחלק הפרקטי ולדוגמאות:
מתי משתמשים ב-API?
בהנחה ואתם עובדים ביום יום עם מערכות אוטומציה NO CODE כמו MAKE או ZAPIER, אני מתאר לעצמי שלרוב התהליכים שאתם עושים יש אפליקציות פנימיות, כמו גוגל שיטס, איירטייבל, GREEN API ועוד.
לפעמים, נרצה לעשות תהליך אוטומציה מול מערכת שאין לה אפליקציה ב-MAKE, כמו מערכת הסליקות והחשבוניות של קארדקום. נכון להיום, אין לקארדקום אפליקציה ב-MAKE שמאפשרת להוציא חשבונית. לכן, ניעזר ב-API של קארדקום שקריאה יחסית פשוטה תאפשר לנו לעשות את זה (כמו שנראה בדוגמאות בהמשך המאמר).
ממה מורכבת קריאת API
בחלק הזה נכיר 8 מושגים חשובים שקשורים לקריאות API שיעזרו לכם להבין בצורה יסודית את הדברים:
1. Endpoint (נקודת קצה)
מה זה?
כתובת URL ספציפית שהמערכת שולחת אליה את קריאת ה-API שלנו.
בד"כ הכתובת תהיה מתוך המערכת שנרצה לגשת אליה עם הוספת \ עדכון מידע.
דוגמה:
https://api.example.com/users
2. Body (גוף הבקשה)
מה זה?
המידע שהמשתמש שולח ל-API כדי לבקש פעולה או מידע.
דוגמה:
"תבדוק אם יש במערכת לקוח עם טלפון 05XXXXX", או "תיצור חשבונית ללקוח X על סכום Y עבור מוצר Z", או "תעדכן את המייל של מספר לקוח ל-[email protected] וכו'...
הבקשות כאן כתובות בטקסט חופשי כמובן שבפועל בגוף הבקשה יהיו טקסט דמוי קוד שמייצג את הפעולה או הפעולות שנרצה לעשות.
3. HTTP Method (שיטת בקשה)
מה זה?
שיטה שמסבירה ל-API איזה פעולה לבצע.
- GET: בקשת מידע (קריאה בלבד).
- POST: שליחת מידע חדש לשרת.
- PUT: עדכון מידע קיים.
- DELETE: מחיקת מידע.
דוגמה:
בהמשך לדוגמאות מהסעיף הקודם:
- חיפוש טלפון של לקוח יהיה בעזרת GET
- כדי ליצור חשבונית נשתמש ב-POST
- ועל מנת לעדכן מייל ללקוח קיים נצטרך לבחור ב-PUT.
4. Headers (כותרות)
מה זה?
מידע נוסף שנשלח יחד עם הבקשה, כמו הרשאות או מפתח גישה.
דוגמה:
מפתח בשם KEY שהערך שלו הוא XYZXYZ (זה בעצם מפתח וסיסמא לצרכי אבטחה שיאפשרו לגשת ל-API הספציפי שאנחנו פונים אליו רק למי שיש אותם)
5. Payload (תוכן הפרמטרים בגוף הבקשה)
מה זה?
המידע העיקרי שנשלח עם הבקשה
דוגמה:
בהמשך לסעיף הקודם, ה-Payload יכיל את כתובת המייל של המשתמש, או הפרטים שלו, או שאר המידע שאנחנו שולחים בתוך ה-BODY.
6. Response (תשובה)
מה זה?
המידע שה-API מחזיר בתגובה לבקשה שלנו.
דוגמה:
"נוצר משתמש חדש במערכת והמספר מזהה שלו הוא 19" (התשובה תהיה באנגלית כמובן)
7. Status Code (קוד סטטוס)
מה זה?
מספר שמסמן אם הבקשה הצליחה או נכשלת, למשל:
- 200: הצלחה
- 404: לא נמצא
- 500: שגיאת שרת
דוגמה:
אם ננסה למחוק משתמש שלא קיים, ה-API יחזיר קוד 404.
8. Authentication (אימות)
מה זה?
שיטה שמתמקדת בפרוטוקולי אבטחה מתקדמים, כך שרק משתמשים מורשים יוכלו לגשת ל-API.
דוגמה:
- Basic Authentication: שילוב של שם משתמש וסיסמה בהצפנת Base64.
- Bearer Token: טוקן מבוסס JWT שנוצר לאחר כניסה למערכת.
- OAuth: פרוטוקול מתקדם יותר שמשתמש באימות מבוסס הרשאות.
ככה נראית קריאת API:
מה שראינו כאן זה בקשה להוספת לקוח במערכת קארדקום.
מה זה תיעוד API (דוקומנטציה) ואיך עובדים איתו?
אוקיי אז הבנו שלמערכת מסוימת אין אפליקציה ב-MAKE ונצטרך קצת להזיע כדי לבנות את האוטומציה המיוחלת. מה עכשיו?
בשלב הזה נרצה לחפש את תיעוד ה-API של אותה המערכת, כדי להבין איך לבנות את קריאת ה-API, ממה היא מורכבת, לאיזה כתובת URL צריך לשלוח את המידע וכו'.
במילים אחרות: דוקומנטציית ה-API נותנת לנו את כל המידע הרלוונטי כדי לגשת למערכת ולבצע את הפעולות שאנחנו רוצים.
ההמלצה שלי היא פשוט לחפש בגוגל את שם המערכת בתוספת "API", וככה להגיע בקלות למסמך הזה. דרך נוספת היא לחפש באתר שלהם או פשוט לבקש מהתמיכה.
בואו נראה 2 דוגמאות כאלה:
תיעוד ה-API של Pipedrive
למערכת ה-CRM של פייפדרייב יש תיעוד API מאוד נוח לשימוש:
חיפוש קל ומהיר בגוגל עם הביטוי "PIPEDRIVE API" יביא אותנו
למסמך תיעוד ה-API של PIPEDRIVE CRM.
ככה הוא נראה מבפנים:
בדרך כלל במסך הפתיחה יש הסבר כללי על הממשק, ובצד המסך יש סרגל עם האובייקטים השונים של המערכת, ובכל אחד מהם מופיעים סדרת הפעולות שאפשר לעשות.
הערה חשובה:
למערכת ה-CRM של Pipedrive יש אפליקציה ב-Make, אז למה בעצם אנחנו צריכים גישה ל-API, אם אפשר לבצע את הפעולות דרך Make?
התשובה פשוטה:
את הפעולות העיקריות אכן אפשר לעשות דרך Make (כמו הוספה או עדכון של לקוחות ועסקאות, או חיפוש רשומות וכו').
ויש פעולות יותר מתקדמות שלא נמצא באפליקציה ב-Make ורק דרך ה-API אפשר לבצע (כמו יצירת רשימה של כל ההערות בכרטיס לקוח מסוים או הוספת וריאציה למוצר ספציפי)
תיעוד ה-API של קארדקום
גם את ממשק ה-API של קארדקום לא קשה למצוא, וחיפוש בגוגל יביא אותנו לכאן:
שלב אחרי שלב: איך מבצעים קריאת API?
הדרך הכי נוחה לבצע קריאות API כחלק מתהליך אוטומציה היא באמצעות MAKE. את הטסטים אפשר ומומלץ לבצע בעזרת הכלי של POSTMAN.
בואו נראה איך אנחנו בונים תהליך אוטומציה שמפיקה חשבונית אוטומטית מתוך מערכת ה-CRM שלנו.
(בחרתי דוגמא קצת מורכבת אבל השימוש הזה נפוץ ומבוקש! בעיקר כשלקוח עושה העברה בנקאית, ונרצה שיקבל חשבונית באופן אוטומטי)
שלבי העבודה:
-
ניגש לתיעוד ה-API של קארדקום (מהסעיף הקודם)
-
נחפש את כתובת ה-URL עבור קריאת ה-API, במקרה שלנו:
https://secure.cardcom.solutions/Interface/CreateInvoice.aspx
-
נחפש את שיטת הקריאה
- בד"כ היא מוזכרת בתחילת המאמר ליד ה-URL, אבל
בדף הזה היא מופיע באמצע כ-POST. אגב, נוכל לשער שמדובר בקריאה מהסוג הזה
כי אנחנו רוצים ליצור רשומה חדש בקארדקום.
-
נחפש את הפרמטרים שמוגדרים כחובה + את אלה שנרצה לשלוח. במקרה שלנו:
|
פרמטר |
משמעות |
|
terminalnumber |
מספר המסוף שלך במערכת Cardcom |
|
username |
שם המשתמש שלך ב-Cardcom |
|
InvoiceType |
סוג החשבונית (300 = חשבון עסקה) |
|
InvoiceHead.CustName |
שם הלקוח שמופיע בחשבונית |
|
InvoiceHead.SendByEmail |
האם לשלוח את החשבונית במייל (true/false) |
|
InvoiceHead.Language |
שפת החשבונית (he = עברית, en = אנגלית) |
|
InvoiceHead.Email |
כתובת המייל של הלקוח |
|
InvoiceHead.IsAutoCreateUpdateAccount |
האם ליצור אוטומטית חשבון ללקוח (true/false) |
|
InvoiceLines.Description |
תיאור הפריט/שירות בחשבונית |
|
InvoiceLines.Price |
מחיר הפריט/שירות |
|
InvoiceLines.Quantity |
כמות הפריטים בחשבונית |
|
CustomPay.TransactionID |
מזהה העסקה הייחודי |
|
CustomPay.TranDate |
תאריך העסקה (בפורמט DD/MM/YYYY) |
|
CustomPay.Description |
תיאור אמצעי התשלום (למשל: "העברה בנקאית") |
|
CustomPay.Asmacta |
מספר אסמכתא לתשלום |
|
CustomPay.Sum |
סכום התשלום הכולל |
-
עכשיו נשאר לנו להזין את המידע במודול HTTP במערכת MAKE, באופן הבא:
שימו לב שיש כמה דרכים להגדיר את הפרמטרים:
- בתוך כתובת ה-URL (כמו שעשיתי בדוגמא)
- כפרמטרים נפרדים ב-QUERY
- בפורמט JSON בסקשן של CONTENT
-
נוודא שקבלנו Response עם Status code תקין
במקרה של קארדקום נרצה לקבל קוד "0" -וככה נדע שהקריאה עברה באופן תקין, בד"כ יופיעו בתיעוד ה-API כל סוגי הStatus code שנוכל לקבל, כמו שקארקום מתארים כאן:
איך מתרגלים קריאות API?
הדרך הכי נוחה שאני ממליץ לתרגל קריאות API היא בעזרת מערכת מסוימת שאתם כבר רשומים אליה,
ופשוט לבצע קריאות. זה יכול מהמערכת של פייפדרייב, פיירברי, קארדקום (כמו בדוגמא) או מערכות נוספות.
פשוט תכנסו לתיעוד ה-API ותתחילו מהפעולות הפשוטות. את הקריאה אפשר לבצע במודול HTTP של MAKE.COM ואפשר גם להיעזר בכלי הפשוט (והחינמי) של POSTMAN.
סיכום
אז אחרי שהבנו מה זה API, למה בכלל צריך אותו ואיך עובדים איתו - מקווה שהבנתם שעולם של קריאות API הוא לא כזה מפחיד, במיוחד כשיש כלים כמו Make ו-Postman שעוזרים להפוך את זה לפשוט ונגיש.
גם אם אתם לא מתכנתים – עם קצת סבלנות, הבנה בסיסית של מבנה הקריאה והיכרות עם התיעוד של המערכת - תוכלו לבצע קריאת API ראשונה עוד היום.
הכי חשוב? עכשיו יש לכם עוד כלי בארגז - ואני בטוח שתשתמשו בו יותר מהר ממה שאתם חושבים, אז שיהיה בהצלחה!
כמו תמיד אפשר לשאול שאלות כאן בתגובות, פידבקים גם יתקבלו בברכה.
לפרטים על הקורס המקיף של אוטומציות בשילוב AI ליצירת ערוץ רווח נוסף או עיקרי
