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

הפקת מסמכים

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

הכנה ואז אישור

  1. הכנה: POST /v1/issuers/{issuerId}/drafts עם הכותרת Idempotency-Key. טרינג בודקת את הבקשה, מחשבת כל סכום ואת המע"מ ושומרת טיוטה ממתינה. שום דבר לא מופק.
  2. אישור: POST /v1/drafts/{draftId}/confirm, בלי גוף. זו הקריאה היחידה שמפיקה.

טיוטה פגה אחרי 24 שעות (expiresAt). תאריך המסמך הוא היום או עד 14 יום אחורה, ולא לפני המסמך האחרון מאותו סוג.

מפתח האידמפוטנטיות

מפתח אחד לכל מסמך שמתכוונים להפיק: 1 עד 255 תווי ASCII מודפסים. בונים אותו ממשהו שכבר יש לכם, כמו מספר ההזמנה וסוג המסמך (order-1001-400), ושומרים אותו עם ההזמנה לפני הקריאה הראשונה.

שולחיםמקבלים
אותו מפתח עם אותה בקשהאותה טיוטה (replayed: true), או המסמך שהיא הפכה אליו (outcome: "document")
אותו מפתח עם בקשה אחרת409 IDEMPOTENCY_KEY_REUSED
מפתח שהטיוטה שלו פגה410 DRAFT_EXPIRED: מכינים מחדש עם מפתח חדש

כשהתוצאה לא ידועה

אחרי כל שגיאה של אישור לא הופק כלום, חוץ מאחת: 504 OUTCOME_UNKNOWN. באותו אופן מתייחסים לכל אלה: אין תשובה, החיבור נותק, פג הזמן אצלכם, או 5xx בלי גוף השגיאה של ה-API.

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

הספריות עושות את זה בשבילכם. אישור נשלח שוב עד 8 פעמים (confirmMaxRetries); אם התוצאה עדיין לא ידועה נזרקת TringOutcomeUnknownError עם ה-draftId לאישור מאוחר יותר. הכנה שהתשובה שלה אבדה נשלחת שוב עם אותו מפתח.

תשובה לאישורמשמעותמה הספרייה עושה
201הופק עכשיומחזירה { document, replayed: false }
200הופק כבר קודםמחזירה { document, replayed: true }
504 OUTCOME_UNKNOWN, אין תשובה, 5xx בלי גוףלא ידועשולחת את אותו אישור שוב
503 ISSUE_TIMEOUT, 500 RENDER_FAILED (render-timeout, browser-unavailable)לא הופק, מותר לחזורשולחת את אותו אישור שוב
409 DRAFT_STALE, 410 DRAFT_EXPIREDלא הופקזורקת שגיאה; מכינים מחדש עם מפתח חדש
429 RATE_LIMITEDלא טופלמחכה Retry-After ושולחת שוב

מגבלות קצב

המגבלות נספרות לדקה, ומעבר להן התשובה היא 429 RATE_LIMITED עם Retry-After בשניות. אלה גם המספרים של סעיף "שימוש הוגן" בתנאי השימוש.

מהבדקה
בקשות לכל מפתח API600
בקשות מכל כתובת רשת1,200
ניסיונות זיהוי שנכשלו מכל כתובת20
הורדות של קובץ מסמך לכל מפתח60

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

חמשת סוגי המסמכים

docTypeשםמה יש בו
400קבלהpayments
305חשבונית מסlines
320חשבונית מס / קבלהlines ו-payments, משולמת במלואה
330חשבונית מס זיכויlines, creditedInvoices, reason
300חשבונית עסקהlines

עוסק פטור מפיק רק 300 ו-400. שורות מקבלות priceMode שהוא net (מחירים לפני מע"מ) או gross (מחירים כולל מע"מ), ו-vatKind שהוא standard, zero או exempt. טרינג לוקחת את שיעור המע"מ שבתוקף בתאריך המסמך; לא שולחים אותו.

חשבונית מס
{
  "docType": 305,
  "documentDate": "2026-11-20",
  "priceMode": "net",
  "customer": { "externalRef": "crm-customer-4711", "name": "ישראלה ישראלי" },
  "lines": [
    { "description": "ייעוץ", "unit": "שעה", "quantity": "1.0000", "unitPrice": "100.00", "vatKind": "standard" }
  ],
  "expectedPaymentMethods": [3, 4]
}

אמצעי תשלום (payments[].method): 1 מזומן, 2 שיק, 3 כרטיס אשראי, 4 העברה בנקאית, 5 תו קנייה, 6 תלוש החלפה, 7 שטר, 8 הוראת קבע, 9 אחר.

סכומים ושדות

  • סכומים הם מחרוזות JSON עם בדיוק שתי ספרות אחרי הנקודה: "118.00". לכמויות ארבע: "1.0000". מספר JSON, "118" או "118.5" נדחים ולא מעוגלים. פונקציות העזר amount() ו-quantity() כותבות אותם בשבילכם.
  • שדה שה-API לא מכיר נדחה (FIELD_UNKNOWN), כך ששדה עם שגיאת כתיב לא נעלם בשקט ממסמך מס.
  • expectedTotal הוא רשות: שולחים את הסכום שאתם מצפים לו, וסכום מחושב אחר נדחה.
  • דחייה היא 422 DOCUMENT_REFUSED עם issues: רשומה לכל סיבה, עם code ועם path של השדה. שום דבר לא נשמר והמפתח נשאר פנוי.

לקוחות

שולחים customer.externalRef (המזהה שלכם ללקוח: בשימוש הראשון הלקוח נוצר, ובהמשך הוא נמצא) או customer.key (המפתח שטרינג החזירה ב-customerKey). בלי אחד מהם כל מסמך יוצר רשומת לקוח חדשה.

מסירה

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

sh
curl -sS -X POST "$TRING_BASE_URL/v1/documents/$DOCUMENT_ID/links" \
  -H "Authorization: Bearer $TRING_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{ "recipientName": "ישראלה ישראלי" }'

התשובה מחזיקה את url ואת token פעם אחת בלבד. GET /v1/documents/{id}/pdf מחזיר העתק חתום לתיק שלכם; GET /v1/documents/{id}/delivery אומר אם הלקוח הוריד את המקור.

תיקונים וביטול

מצבמה עושים
המקור לא יצא מהעסק, והעסק מצהיר שהמסמך עוד לא דווחPOST /v1/documents/{id}/cancellation עם "declaredUnreported": true
חשבונית מס (305, 320) אחרי שהמקור יצאחשבונית זיכוי: docType 330 עם creditedInvoices
קבלה אחרי שהמקור יצאקבלת ביטול: docType 400 עם corrects: { docType: 400, number }
חשבונית עסקה אחרי שהמקור יצא300 מתקנת עם corrects ועם effect שהוא credit או charge

ביטול אחרי שהמקור יצא עונה 409 ORIGINAL_RELEASED, ו-details.correction אומר איזה מסמך להפיק במקום.

עיצוב המסמכים

עסק בוחר איך המסמכים שלו נראים: תבנית, צבע הדגשה, גופן ושורת תחתית. GET /v1/issuers/{issuerId}/design קורא את העיצוב שבתוקף; PUT שומר גרסה חדשה.

js
const { created, design } = await tring.putDocumentDesign(issuerId, {
  template: 'modern', // classic, modern, minimal, warm
  accent: '#6d28d9',
  font: 'heebo', // assistant, heebo, rubik, open-sans, noto-sans-hebrew
  footerText: 'תודה שבחרתם בנו',
});
  • עיצוב חל על מסמכים שמופקים אחריו. מסמך שכבר הופק שומר את העיצוב שלו בכל עותק.
  • שליחת העיצוב שכבר בתוקף לא שומרת כלום ועונה "created": false, כך שמותר לחזור על הקריאה.
  • שמירה צריכה מפתח עם ההרשאה businesses; קריאה צריכה read.
  • עיצוב שאי אפשר לשמור עונה 422 DESIGN_REFUSED, ו-details אומרים איזה שדה ולמה: unknown, format, contrast (עם suggestion לצבע), too-long, reserved-word, mixed-word (אות לטינית, ספרה או סימן בין שתי אותיות עבריות), character, long-number.

שגיאות

לכל שגיאה אותו גוף: { "error": { "code", "message", "details", "issues"?, "requestId" } }. בודקים לפי code. כשמדווחים על בעיה מצרפים את requestId. הרשימה המלאה לכל פעולה נמצאת במדריך ה-API.