טרינג למפתחים English

התחלה מהירה

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

1. מפתח ועסק

צריך שני ערכים:

  • מפתח API של סביבת הניסוי. הוא מתחיל ב-kbl_test_. שומרים אותו במנהל הסודות או בקובץ .env, אף פעם לא בקוד.
  • המזהה של עסק (issuerId) שנתן הרשאה למפתח. GET /v1/issuers מחזיר את הרשימה.

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

sh
npx tring-mock-server

2. התקנה

sh
npm install tring-sdk

3. משתני סביבה

sh
export TRING_API_KEY=kbl_test_...
export TRING_ISSUER_ID=...
export TRING_BASE_URL=https://sandbox.tring.co.il   # או הכתובת ששרת הדמה הדפיס

הספריות קוראות את המשתנים האלה. בלי TRING_BASE_URL הן בוחרות בסביבת הניסוי למפתח kbl_test_ ובייצור למפתח kbl_live_.

4. הפקת קבלה

examples/js/quickstart.mjs
// Issue a receipt in the sandbox: prepare, look, confirm.
// Run: node quickstart.mjs   (reads TRING_API_KEY, TRING_ISSUER_ID and, if set, TRING_BASE_URL)
import { Tring, DocType, PaymentMethod, amount, todayInIsrael } from 'tring-sdk';

const tring = new Tring();
const issuerId = process.env.TRING_ISSUER_ID;

// 1. Prepare: Tring checks the request and computes every amount. Nothing is issued yet.
const prepared = await tring.prepareDraft(
  issuerId,
  {
    docType: DocType.Receipt,
    documentDate: todayInIsrael(),
    customer: { externalRef: 'crm-customer-4711', name: 'ישראלה ישראלי' },
    payments: [{ method: PaymentMethod.BankTransfer, amount: amount(118) }],
    paymentDate: todayInIsrael(),
    paymentNature: 'ייעוץ לדוגמה',
  },
  { idempotencyKey: 'order-1001-receipt' }, // one key per document, from your order number
);

if (prepared.outcome === 'document') {
  // This key was used before and its draft became a document: nothing new is issued.
  console.log(`Already issued: receipt number ${prepared.document.number}`);
} else {
  console.log(`Draft ${prepared.draft.id}, total ${prepared.draft.document.amounts.total}`);

  // 2. Confirm: this issues the document. Sending it again returns the same document.
  const { document } = await tring.confirmDraft(prepared.draft.id);
  console.log(`Issued: receipt number ${document.number}`);
}

הריצו פעמיים. בפעם השנייה יודפס "Already issued": אותו Idempotency-Key עם אותה בקשה מחזיר את המסמך שהטיוטה הפכה אליו, ושום דבר חדש לא מופק. זה מה שהופך שליחה חוזרת לבטוחה.

5. מה קרה

שלבקריאהתוצאה
הכנהPOST /v1/issuers/{issuerId}/draftsבודקת את הבקשה, מחשבת סכומים ומע"מ ושומרת טיוטה ל-24 שעות. לא נלקח מספר.
אישורPOST /v1/drafts/{draftId}/confirmלוקח את המספר הבא, מפיק, חותם ושומר את המקור.

בין שתי הקריאות מציגים את הטיוטה (או את ה-PDF שלה, GET /v1/drafts/{draftId}/preview) למי שמאשר.

הלאה

  • הפקת מסמכים: ארבעת הסוגים האחרים, תיקונים, ומה עושים כשתשובה הולכת לאיבוד.
  • סוכני AI ו-MCP: לתת ל-Claude Code או ל-Cursor להכין טיוטות.