הפקת מסמכים
מסמך שהופק הוא סופי: שום דבר לא משנה או מוחק אותו. לכן הפקה היא שתי קריאות, ולכן לשליחה חוזרת יש כללים קשיחים.
הכנה ואז אישור
- הכנה:
POST /v1/issuers/{issuerId}/draftsעם הכותרתIdempotency-Key. טרינג בודקת את הבקשה, מחשבת כל סכום ואת המע"מ ושומרת טיוטה ממתינה. שום דבר לא מופק. - אישור:
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 בשניות. אלה גם המספרים של סעיף "שימוש הוגן" בתנאי השימוש.
| מה | בדקה |
|---|---|
| בקשות לכל מפתח API | 600 |
| בקשות מכל כתובת רשת | 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). בלי אחד מהם כל מסמך יוצר רשומת לקוח חדשה.
מסירה
המקור אף פעם לא מגיע למערכת שלכם. מבקשים מטרינג קישור אישי ושולחים אותו ללקוח: ההורדה הראשונה היא ה"מקור", וכל הורדה אחריה היא העתק.
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 שומר גרסה חדשה.
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: 'תודה שבחרתם בנו',
});result = tring.put_document_design(issuer_id, {
"template": "modern",
"accent": "#6d28d9",
"font": "heebo",
"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.