התחלה מהירה
נפיק קבלה על 118.00 בסביבת הניסוי. על מסמכי ניסוי מודפסת השורה "דוגמה בלבד", והם אינם מסמכי מס.
1. מפתח ועסק
צריך שני ערכים:
- מפתח API של סביבת הניסוי. הוא מתחיל ב-
kbl_test_. שומרים אותו במנהל הסודות או בקובץ.env, אף פעם לא בקוד. - המזהה של עסק (
issuerId) שנתן הרשאה למפתח.GET /v1/issuersמחזיר את הרשימה.
עוד אין מפתח? מריצים את שרת הדמה המקומי. הוא עונה כמו ה-API, מקבל כל מפתח kbl_test_ ומדפיס את שלושת הערכים לייצוא:
npx tring-mock-server2. התקנה
npm install tring-sdkpip install tring-sdk# מספיקים curl ו-jq
jq --version3. משתני סביבה
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. הפקת קבלה
// 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}`);
}"""Issue a receipt in the sandbox: prepare, look, confirm.
Run: python quickstart.py (reads TRING_API_KEY, TRING_ISSUER_ID and, if set, TRING_BASE_URL)
"""
import os
from tring_sdk import DocType, PaymentMethod, Tring, amount, today_in_israel
tring = Tring()
issuer_id = os.environ["TRING_ISSUER_ID"]
# 1. Prepare: Tring checks the request and computes every amount. Nothing is issued yet.
prepared = tring.prepare_draft(
issuer_id,
{
"docType": DocType.RECEIPT,
"documentDate": today_in_israel(),
"customer": {"externalRef": "crm-customer-4711", "name": "ישראלה ישראלי"},
"payments": [{"method": PaymentMethod.BANK_TRANSFER, "amount": amount(118)}],
"paymentDate": today_in_israel(),
"paymentNature": "ייעוץ לדוגמה",
},
idempotency_key="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.
print(f"Already issued: receipt number {prepared['document']['number']}")
else:
draft = prepared["draft"]
print(f"Draft {draft['id']}, total {draft['document']['amounts']['total']}")
# 2. Confirm: this issues the document. Sending it again returns the same document.
document = tring.confirm_draft(draft["id"])["document"]
print(f"Issued: receipt number {document['number']}")#!/bin/sh
# Issue a receipt with curl: prepare, then confirm.
# Needs TRING_BASE_URL, TRING_API_KEY, TRING_ISSUER_ID, and jq.
set -eu
TODAY=$(TZ=Asia/Jerusalem date +%F)
# 1. Prepare: nothing is issued yet. Keep draft.id.
PREPARED=$(curl -sS -X POST "$TRING_BASE_URL/v1/issuers/$TRING_ISSUER_ID/drafts" \
-H "Authorization: Bearer $TRING_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-1001-receipt" \
--data @- <<JSON
{
"docType": 400,
"documentDate": "$TODAY",
"customer": { "externalRef": "crm-customer-4711", "name": "ישראלה ישראלי" },
"payments": [{ "method": 4, "amount": "118.00" }],
"paymentDate": "$TODAY",
"paymentNature": "ייעוץ לדוגמה"
}
JSON
)
if [ "$(echo "$PREPARED" | jq -r .outcome)" = "document" ]; then
echo "Already issued: receipt number $(echo "$PREPARED" | jq -r .document.number)"
exit 0
fi
DRAFT_ID=$(echo "$PREPARED" | jq -r .draft.id)
echo "Draft $DRAFT_ID, total $(echo "$PREPARED" | jq -r .draft.document.amounts.total)"
# 2. Confirm: this issues the document. Sending it again returns the same document.
curl -sS -X POST "$TRING_BASE_URL/v1/drafts/$DRAFT_ID/confirm" \
-H "Authorization: Bearer $TRING_API_KEY" | jq -r '"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 להכין טיוטות.