אינטגרציה עם TON API: קבלת תשלומים, יתרות Jettons תוך 1-2 ימים

אינטגרציה של TON API: היכן נשבר רישום התקבולים

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

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

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

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

גרוע מכך — העברות "תקועות": השליחה עברה, האישור לא הגיע, התשלום אינו נראה לא ברישום ולא בדוח, והלקוח כבר כתב לתמיכה.

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

מה נותנת אינטגרציה ישירה: מהירות והתאמת יתרות

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

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

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

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

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

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

דרכי קבלת תשלומים: קסטודיאלי, לא-קסטודיאלי, היברידי

קבלת תשלומים ברשת TON היא прежде всего שאלה של מי מחזיק במפתחות הפרטיים ומי חותם על משיכת הכספים. אחזקת המפתחות קובעת גם את עלות התמיכה וגם את מהירות המשיכה המקסימלית שאתם מבטיחים למשתמש.

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

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

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

סדר ההטמעה: מאודיט של הסכימה ועד מסירה לתמיכה

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

1. אודיט של הסכימה הנוכחית. מפרקים איך כיום נרשמים התקבולים: איזה פנקס פעולות נחשב למקור האמת, אילו כתובות וחוזים מעורבים, והיכן הדוחות והרישום הפנימי אינם מתיישבים. התוצאה — מפת מצב קיים עם רשימת אי-ההתאמות, והיא גם נקודת הקבלה של השלב.
2. סכימת זרמי התשלומים. מתכננים את הכתובת של העברות נכנסות: מזהה תשלום ייחודי או כתובת נפרדת לכל לקוח, כללי התאמה בין ההעברה להזמנה, טיפול בתשלומי חסר ובחזרות, וקריאת יתרות Jettons. הסכימה המאושרת — קבלת השלב.
3. רשת בדיקות. מקימים קונטור על מטבעות בדיקה ומריצים תרחישים: תשלום מוצלח, תשלום חסר, שליחה חוזרת, העברה בטוקן הלא נכון, תשלום לפי חשבונית שפגה.
4. בדיקת כשל. מנתקים את הקשר עם הצומת, מכפילים התראות על טרנזקציה, מעכבים אישור. המטרה — העברה אחת לא יוצרת תשלום שני, ואי-התאמות נתפסות בהתאמה לפי לוח זמנים.
5. קבלה לפי נוהל. משווים יתרות ואת פנקס הפעולות לפי צ'ק-ליסט, כל אי-התאמה מפורקת עד אפס. השלב לא נסגר עד שסכומי הביקורת מתיישבים.
6. מסירה לתמיכה. מוסרים תיעוד, סכימת זרמים, הרשאות, יומנים ונוהל תגובה לאירועים, ומאמנים את המשמרת התורנית.

אחרי זה האינטגרציה של TON API מתנהלת כמו שירות רגיל — אפשר לפתח אותה בלי לבנות מחדש את קונטור התשלומים.

קונפיגורציות, סכימות ונהלים שנשארים אצלכם

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

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

• תיעוד האינטגרציה — אילו מתודות קוראים ליצירת חשבונית, למעקב אחרי תקבול ולקריאת יתרות Jettons; מבנה הבקשות והתשובות, פירוק קודי שגיאה וכלל חד-משמעי כיצד להגיב לכל אחד מהם.
• סכימת אחסון המפתחות — היכן פיזית נמצאים מפתחות הארנק, מי ולפי איזה אלגוריתם מקבל אליהם גישה, סדר הרוטציה ורצף הפעולות בחשד לחשיפה.
• מדיניות גישה — תפקידים של שירותים ואנשים, ההרשאות המינימליות הנדרשות, והפרדה בין קונטור קבלת התשלומים לקונטור משיכת הכספים, כך שדליפה של גישה אחת לא תפתח את כל הארנק.
• נוהל טיפול בתקלות — ההתנהגות כשהיצעים חיצוניים אינם זמינים וכשאישור מתעכב, כללי ניסיונות חוזרים, הרגע שממנו התשלום נחשב סופי, וסדר התאמת אי-ההתאמות.
• מדריך לתמיכה — פירוק של פניות אופייניות (הטרנזקציה לא נראית, הסכום לא התיישב, הסטטוס תקוע), היכן להסתכל ביומנים, מה לענות למשתמש ובאיזה שלב לחבר מהנדסים.
• סכימת זרמים ומצבים — המסלול מהנפקת חשבונית ועד לזיכוי, עם נקודות שמירת מצב מסומנות: אחרי הפעלה מחדש של השירות אף תשלום לא הולך לאיבוד ולא מוכפל.
• צ'ק-ליסט קבלה ועדכונים — סט בדיקות לאחר שינויים בצד הרשת החיצונית ורשימת מדדים שחייבים להיות בניטור, כדי לזהות דעיכה לפני תלונות לקוחות.

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

מקרה בוחן: קבלת תשלומים בלי התאמות ידניות ובלי העברות אבודות

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

בשעות הערב התור הגיע לעשרות העברות, ושיעור הפעולות שדרשו בדיקה ידנית עמד על 100% — בלי אדם לא עברה אף עסקה.

מה שינו

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

מה התקבל

• שיעור הפעולות עם בדיקה ידנית — מ-100% ל-4%, והשאר נסגר אוטומטית בתוך דקות;
• זמן התגובה לאי-התאמת יתרות — מכמה שעות ל-10-15 דקות, וכשאנחנו יודעים על הבעיה לפני הלקוח;
• תור ההעברות בערב נעלם כתופעה: התמיכה עוסקת במקרים שנויים במחלוקת ולא בהתאמות.

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

אם קבלת התשלומים כבר פועלת דרך שירות צד שלישי

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

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

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

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

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

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

ספקות טכניים: אישורים, מגבלות, גישה למפתחות

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

האם יש מגבלות על משיכה?

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

האם אתם מקבלים גישה למפתחות פרטיים?

לא. החתימה נשארת בקונטור שלכם — אנחנו מתחברים במפתח עם הרשאות מוגבלות ורואים רק כתובות ונתונים פומביים.

מה קורה עם עיבוד חוזר של פעולות?

כל פעולה מסומנת לפי ה-hash: התראה חוזרת מהרשת לא יוצרת תשלום שני ולא מכפילה את היתרה.

מה עושים כאשר צומת הרשת אינו זמין?

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

נדון במשימה: ננתח את הסכימה ונחזור עם תוכנית עבודה

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

שלחו בצורה חופשית את מה שכבר exists:

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

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