חיבור מערכות גבייה ב־API: תשלומים, סטטוסים ודוחות בלי עבודה כפולה

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

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

ממשק גבייה עשוי להעביר מידע עסקי ואישי ולכן אין להסתמך על URL סודי. יש להשתמש ב-HTTPS, אימות מתאים, הגבלת הרשאות וניהול סודות מחוץ לקוד.

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

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

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

Webhooks מאפשרים לשלוח אירוע בזמן קרוב להתרחשותו, בעוד polling מאפשר למערכת הלקוח לשאול מדי פעם מה השתנה. לעיתים משלבים ביניהם: webhook לעדכון מהיר ו-endpoint משיכה לצורך reconciliation.

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

כל העברה צריכה להיות ניתנת למעקב באמצעות correlation ID או מזהה דומה. לוג תפעולי צריך להסביר מה התקבל, מה נדחה ומה ממתין ל-retry — תוך הימנעות מחשיפת מידע רגיש שלא נחוץ ללוג.

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