שילוב API של TON: עיבוד תשלומים ויתרות Jetton תוך 1-2 ימים

מפתח עם עשר שנות ניסיון ב-Solidity מנסה לשלוח את עסקת ה-TON הראשונה שלו — ומקבל שגיאת תאימות כתובת. פורמט 0x... לא עובד; הלוגיקה של EVM לא ישימה: TON בנוי על ארכיטקטורת שחקנים (actor architecture), חוזים חכמים נכתבים ב-FunC או Tact, וכתובות מגיעות בשלושה פורמטים. ללא הבנה ברורה של ההבדלים הללו, האינטגרציה הופכת לשבוע של ניפוי באגים. המהנדסים שלנו, עם 5 שנות ניסיון בבלוקצ'יין, פיתחו גישה שמצמצמת אינטגרציה טיפוסית ל-1–2 ימים במפתח מלא. אנו לוקחים על עצמנו את כל הסיכונים הקשורים לבחירת API, המרת כתובות, הגדרת webhooks ובדיקות ב-testnet. אנו מבטיחים עיבוד תקין של תשלומים ויתרות.

איך לבחור API עבור TON?

TON Center API הוא RPC ציבורי, חינמי עם מגבלות (1 בקשה/שנייה ללא מפתח, 10 בקשות/שנייה עם מפתח). מספיק לאבות טיפוס. TON Console (tonconsole.com) הוא API בתשלום עם מגבלות גבוהות יותר, SDK ו-webhooks. זהו התקן הייצור לפרויקטים בעומס גבוה. אנו ממליצים עליו לפתרונות מסחריים. TonWeb (חבילת tonweb npm) ו-@ton/ton (ה-SDK הרשמי) הם ספריות הלקוח העיקריות. לפרויקטים חדשים, @ton/ton מועדף.

השוואת SDKs של TON

@ton/ton משולב באופן הדוק עם TON Console ומספק חוזים טיפוסיים (typed contracts). לפרויקטים חדשים, זו הבחירה הברורה.

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

כתובות TON מגיעות בשלושה פורמטים:

import { Address } from "@ton/ton"; // Raw формат: workchain:hex const raw = "0:abcdef1234567890..."; // User-friendly: bounceable (для контрактов) const bounceable = "EQCr..."; // начинается с EQ // User-friendly: non-bounceable (для кошельков при первой отправке) const nonBounceable = "UQCr..."; // начинается с UQ const addr = Address.parse(bounceable); console.log(addr.toRawString()); // 0:... console.log(addr.toString()); // EQ... console.log(addr.toString({ bounceable: false })); // UQ... 

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

איך לקבל יתרה ולנטר עסקאות?

import { TonClient, Address } from "@ton/ton"; const client = new TonClient({ endpoint: "https://toncenter.com/api/v2/jsonRPC", apiKey: process.env.TON_CENTER_API_KEY, }); async function getTonBalance(address: string): Promise<bigint> { const addr = Address.parse(address); return client.getBalance(addr); // Возвращает nanotons (1 TON = 1e9 nanotons) } // Для Jetton (TON токены) нужен другой подход — через Jetton wallet контракт async function getJettonBalance( ownerAddress: string, jettonMasterAddress: string ): Promise<bigint> { const master = client.open(JettonMaster.create(Address.parse(jettonMasterAddress))); const walletAddress = await master.getWalletAddress(Address.parse(ownerAddress)); const wallet = client.open(JettonWallet.create(walletAddress)); const data = await wallet.getWalletData(); return data.balance; } 

ל-TON אין יומני אירועים כמו ב-Ethereum. לניטור תשלומים נכנסים — סקרו את רשימת העסקאות של הכתובת:

async function getTransactions(address: string, limit = 20) { const response = await fetch( `https://toncenter.com/api/v2/getTransactions?` + `address=${address}&limit=${limit}&archival=true`, { headers: { "X-API-Key": process.env.TON_CENTER_API_KEY! } } ); const { result } = await response.json(); return result; } // Новее — через TON API v3 (tonapi.io) async function getIncomingPayments(address: string, afterLt?: string) { const params = new URLSearchParams({ account: address, limit: "50", ...(afterLt && { after_lt: afterLt }), }); const response = await fetch( `https://tonapi.io/v2/accounts/${address}/transactions?${params}`, { headers: { Authorization: `Bearer ${process.env.TONAPI_KEY}` } } ); return response.json(); } 

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

איך לשלוח TON עם הערה?

import { WalletContractV4, internal } from "@ton/ton"; import { mnemonicToPrivateKey } from "@ton/crypto"; async function sendTon(toAddress: string, amount: bigint, comment?: string) { const keyPair = await mnemonicToPrivateKey(process.env.MNEMONIC!.split(" ")); const wallet = WalletContractV4.create({ publicKey: keyPair.publicKey, workchain: 0, }); const contract = client.open(wallet); const seqno = await contract.getSeqno(); await contract.sendTransfer({ secretKey: keyPair.secretKey, seqno, messages: [ internal({ to: toAddress, value: amount, // в nanotons bounce: false, body: comment, // текстовый комментарий к переводу }), ], }); } 

ההערה (body) היא טקסט שרירותי עד 127 בתים. היא משמשת לזיהוי תשלום (לדוגמה, מספר הזמנה).

איך להגדיר Webhooks לייצור?

לייצור, webhooks עדיפים על פני סקירה תקופתית:

// Регистрация webhook в TON Console Dashboard // POST https://console.tonconsole.com/api/v1/webhook { "url": "https://your-backend.com/webhooks/ton", "accounts": ["EQCr..."], // адреса для мониторинга "event_types": ["transaction"] } // Обработчик app.post("/webhooks/ton", (req, res) => { const { account, transactions } = req.body; for (const tx of transactions) { if (tx.in_msg && tx.in_msg.value > 0) { // Входящий платёж processPayment(account, tx.in_msg.value, tx.hash); } } res.sendStatus(200); }); 

Webhooks דרך TON Console הם דרך אמינה להימנע מאובדן עסקאות. אנו מגדירים נקודות קצה עם ניסיונות חוזרים וטיפול בכפילויות כדי להבטיח מעקב עם זמינות של 99.9%.

שגיאות אינטגרציה טיפוסיות

מה כלול באינטגרציה במפתח מלא

• ביקורת דרישות ובחירת API אופטימלית
• הגדרת לקוח TON והמרת כתובות
• מודול קבלת יתרה (TON + Jettons)
• הטמעת ניטור תשלומים נכנסים (סקירה או webhooks)
• אינטגרציה של שליחת TON עם הערות
• בדיקות ב-testnet וב-mainnet
• תיעוד API ואינטגרציה
• חודש תמיכה לאחר השקה

תהליך

1. ניתוח — אנו לומדים את המשימה והארכיטקטורה הנוכחית שלכם
2. עיצוב — אנו בוחרים API ומתכננים טיפול בשגיאות
3. יישום — אנו כותבים קוד ומחברים SDK
4. בדיקות — אנו מריצים על testnet ובודקים תרחישים
5. פריסה — אנו מפרסמים לייצור ומגדירים ניטור
6. תמיכה — אנו מתקנים באגים ומייעצים למשך 30 יום

אנו נעריך את הפרויקט שלכם בחינם — צרו קשר לייעוץ. אינטגרציית TON API לעיבוד תשלומים בסיסי וניטור: בין 1 ל-2 ימים, כולל בדיקות testnet. חסכו עד 70% מזמן הפיתוח בהשוואה ליישום עצמי.

לפרטים נוספים על ארכיטקטורת TON, ראו ויקיפדיה. לשימוש ב-SDK, עיינו במאגר הרשמי @ton/ton ב-GitHub.