interface KoinlyTransaction {
  date: string; // "2024-01-15 14:30:00 UTC"
  sentAmount: string; // "" если не отправляли
  sentCurrency: string;
  receivedAmount: string; // "" если не получали
  receivedCurrency: string;
  feeAmount: string;
  feeCurrency: string;
  netWorthAmount: string; // USD стоимость в момент транзакции
  netWorthCurrency: string; // "USD"
  label: string; // "trade" | "income" | "airdrop" | "staking" | "fork" | "mining" | "reward" | "transfer"
  description: string;
  txHash: string;
}

function exportToKoinlyCSV(transactions: InternalTransaction[]): string {
  const headers = [
    "Date",
    "Sent Amount",
    "Sent Currency",
    "Received Amount",
    "Received Currency",
    "Fee Amount",
    "Fee Currency",
    "Net Worth Amount",
    "Net Worth Currency",
    "Label",
    "Description",
    "TxHash"
  ];

  const rows = transactions.map(tx => {
    const koinlyLabel = mapCategoryToKoinlyLabel(tx.taxCategory);
    return [
      formatForKoinly(tx.timestamp),
      tx.amountOut?.toString() ?? "",
      tx.assetOut ?? "",
      tx.amountIn?.toString() ?? "",
      tx.assetIn ?? "",
      tx.feeAmount?.toString() ?? "",
      tx.feeCurrency ?? "",
      tx.usdValue?.toFixed(2) ?? "",
      "USD",
      koinlyLabel,
      tx.notes ?? `${tx.source} transaction`,
      tx.txHash ?? "",
    ].join(",");
  });

  return [headers.join(","), ...rows].join("\n");
}

function mapCategoryToKoinlyLabel(category: TaxCategory): string {
  const map: Record<TaxCategory, string> = {
    [TaxCategory.SWAP]: "trade",
    [TaxCategory.STAKING_REWARD]: "staking",
    [TaxCategory.AIRDROP]: "airdrop",
    [TaxCategory.MINING_REWARD]: "mining",
    [TaxCategory.HARD_FORK]: "fork",
    [TaxCategory.TRANSFER]: "transfer",
    [TaxCategory.BUY]: "", // Koinly определяет сам
    [TaxCategory.SELL]: "",
    [TaxCategory.LENDING_INTEREST]: "income",
    [TaxCategory.REFERRAL]: "reward",
  };
  return map[category] || "";
}

חשוב למפות קטגוריות עסקאות בצורה נכונה. לדוגמה, interface KoinlyTransaction { date: string; // "2024-01-15 14:30:00 UTC" sentAmount: string; // "" если не отправляли sentCurrency: string; receivedAmount: string; // "" если не получали receivedCurrency: string; feeAmount: string; feeCurrency: string; netWorthAmount: string; // USD стоимость в момент транзакции netWorthCurrency: string; // "USD" label: string; // "trade" | "income" | "airdrop" | "staking" | "fork" | "mining" | "reward" | "transfer" description: string; txHash: string; } function exportToKoinlyCSV(transactions: InternalTransaction[]): string { const headers = [ "Date", "Sent Amount", "Sent Currency", "Received Amount", "Received Currency", "Fee Amount", "Fee Currency", "Net Worth Amount", "Net Worth Currency", "Label", "Description", "TxHash" ]; const rows = transactions.map(tx => { const koinlyLabel = mapCategoryToKoinlyLabel(tx.taxCategory); return [ formatForKoinly(tx.timestamp), tx.amountOut?.toString() ?? "", tx.assetOut ?? "", tx.amountIn?.toString() ?? "", tx.assetIn ?? "", tx.feeAmount?.toString() ?? "", tx.feeCurrency ?? "", tx.usdValue?.toFixed(2) ?? "", "USD", koinlyLabel, tx.notes ?? `${tx.source} transaction`, tx.txHash ?? "", ].join(","); }); return [headers.join(","), ...rows].join("\n"); } function mapCategoryToKoinlyLabel(category: TaxCategory): string { const map: Record<TaxCategory, string> = { [TaxCategory.SWAP]: "trade", [TaxCategory.STAKING_REWARD]: "staking", [TaxCategory.AIRDROP]: "airdrop", [TaxCategory.MINING_REWARD]: "mining", [TaxCategory.HARD_FORK]: "fork", [TaxCategory.TRANSFER]: "transfer", [TaxCategory.BUY]: "", // Koinly определяет сам [TaxCategory.SELL]: "", [TaxCategory.LENDING_INTEREST]: "income", [TaxCategory.REFERRAL]: "reward", }; return map[category] || ""; } → SWAP, trade → STAKING_REWARD. הטבלה שלהלן מציגה את ההתאמה:

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

מדוע Partner API אמין יותר מ-CSV

ה-Partner API מבטל העלאה ידנית ומפחית את הסיכון לשגיאות. נתונים מועברים באופן מיידי בקבוצות של עד 1,000 עסקאות. עבור נפחים של מעל 10,000 עסקאות בחודש, ה-API אמין פי 5 מ-CSV. תיעוד ה-Partner API של Koinly מאשר כי 99.9% מהעסקאות מעובדות ללא שגיאות כאשר היישום נכון.

// Партнёрская интеграция через Koinly API
async function syncToKoinly(userId: string, koinlyApiKey: string): Promise<void> {
  const transactions = await db.getUnsyncedTransactions(userId);
  await fetch("https://api.koinly.io/api/v2/transactions", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${koinlyApiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      transactions: transactions.map(formatForKoinlyAPI),
    }),
  });
  await db.markSyncedToKoinly(userId, transactions.map(t => t.id));
}

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

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

אנו מטפלים במקרים אלה במהלך בדיקות עם סט בדיקה של 1000+ עסקאות.

כיצד דוגמה אמיתית עובדת

אחד הלקוחות שלנו הוא בורסה עם 20,000 עסקאות ביום. קובץ ה-CSV שקל 50 MB. יישמנו יצירת זרם: חילקנו נתונים לקבוצות של 1,000 רשומות והוספנו משימת רקע להגשה אוטומטית דרך ה-API שלהם (נקודת קצה מותאמת אישית). לא התעוררו בעיות העלאה; משתמשים יכלו לייצא נתונים בלחיצה אחת. למידע נוסף על פורמט ה-CSV של Koinly ומיסוי קריפטו, ראה ויקיפדיה.

תהליך יישום כולל

אנו עוברים חמישה שלבים:

1. ניתוח — חקר סכמת העסקאות של הפלטפורמה שלך, סוגי פעולות, שדות. זיהוי מקרים לא סטנדרטיים.
2. עיצוב — בחירת CSV, API או גישה משולבת. אופטימיזציה של מיפוי קטגוריות לדרישות Koinly.
3. יישום — כתיבת קוד יצירת CSV או נקודת קצה API. חיבור webhooks לעדכונים. מחסנית: TypeScript, Node.js, PostgreSQL.
4. בדיקות — הרצת סט בדיקה של 1000+ עסקאות, השוואה לפלט של Koinly. שימוש בסקריפטים אוטומטיים.
5. פריסה — פריסה לסביבת ייצור, הגדרת ניטור דרך Tenderly ורישום לוגים.

מה כלול

• תיעוד של פורמט CSV ו-API (מפרט OpenAPI).
• גישה לסביבת הבדיקה של Koinly.
• הדרכת צוות על הוספת סוגי עסקאות חדשים.
• חודש תמיכה לאחר השחרור — תיקון כל אי-התאמה.

לוחות זמנים ואחריות

אינטגרציית CSV בסיסית: 1 עד 2 ימים. מלאה עם Partner API: 3 עד 5 ימים. אנו מבטיחים הצגה נכונה של עסקאות ב-Koinly ועמידה בכל התוויות. קבל הערכת פרויקט חינם — צור קשר. אנו מספקים גם תעודת התאמה עם סיום.

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