Issuing documents
A document is final: nothing changes or deletes it once it is issued. That is why issuing takes two calls and why retries follow strict rules.
Prepare, then confirm
- Prepare with
POST /v1/issuers/{issuerId}/draftsand anIdempotency-Keyheader. Tring validates the request, computes every amount and the VAT, and stores a pending draft. Nothing is issued. - Confirm with
POST /v1/drafts/{draftId}/confirm, no body. This is the only call that issues.
A draft expires after 24 hours (expiresAt). The document date is today or up to 14 days back, and never before the latest document of the same type.
The Idempotency-Key
One key per document you mean to issue: 1 to 255 printable ASCII characters. Make it from something you already hold, such as the order number and the type (order-1001-400), and store it with the order before the first call.
| You send | You get |
|---|---|
| The same key with the same request | The same draft (replayed: true), or the document it became (outcome: "document") |
| The same key with a different request | 409 IDEMPOTENCY_KEY_REUSED |
| A key whose draft expired | 410 DRAFT_EXPIRED: prepare again under a new key |
When the outcome is unknown
After every error of a confirm nothing was issued, except one: 504 OUTCOME_UNKNOWN. Treat these the same way: no answer, a cut connection, your own timeout, a 5xx without the API's error body.
Important: send the same confirm again until it answers. Never prepare again under a new Idempotency-Key after an unknown outcome: that can issue a second document for the same sale.
The SDKs do this for you. A confirm is sent again up to 8 times (confirmMaxRetries); if the outcome is still unknown they throw TringOutcomeUnknownError with the draftId to confirm later. A prepare whose answer was lost is sent again with the same key.
| Answer of a confirm | Meaning | The SDK |
|---|---|---|
| 201 | Issued now | returns { document, replayed: false } |
| 200 | Already issued earlier | returns { document, replayed: true } |
504 OUTCOME_UNKNOWN, no answer, bare 5xx | Unknown | sends the same confirm again |
503 ISSUE_TIMEOUT, 500 RENDER_FAILED (render-timeout, browser-unavailable) | Nothing issued, may repeat | sends the same confirm again |
409 DRAFT_STALE, 410 DRAFT_EXPIRED | Nothing issued | throws; prepare again under a new key |
429 RATE_LIMITED | Not processed | waits Retry-After, sends again |
Rate limits
Limits are counted per minute; past one the answer is 429 RATE_LIMITED with Retry-After in seconds. These are also the numbers of the "fair use" section of the terms of service (Hebrew).
| What | Per minute |
|---|---|
| Requests per API key | 600 |
| Requests per network address | 1,200 |
| Failed authentications per address | 20 |
| Document file downloads per key | 60 |
The number of documents is not limited. Up to 2,500 documents a calendar month per business is normal use; above it we offer a volume plan, and issuing is never stopped.
The five document types
docType | Name | Holds |
|---|---|---|
| 400 | Receipt (קבלה) | payments |
| 305 | Tax invoice (חשבונית מס) | lines |
| 320 | Tax invoice / receipt (חשבונית מס / קבלה) | lines and payments, paid in full |
| 330 | Credit tax invoice (חשבונית מס זיכוי) | lines, creditedInvoices, reason |
| 300 | Transaction invoice (חשבונית עסקה) | lines |
An exempt dealer (עוסק פטור) issues only 300 and 400. Lines take priceMode net (prices before VAT) or gross (prices include VAT) and vatKind standard, zero or exempt. Tring takes the VAT rate in force on the document date; you never send it.
{
"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]
}Payment methods (payments[].method): 1 cash, 2 cheque, 3 credit card, 4 bank transfer, 5 voucher, 6 exchange slip, 7 note, 8 standing order, 9 other.
Amounts and fields
- Amounts are JSON strings with exactly two decimals:
"118.00". Quantities have four:"1.0000". A JSON number,"118"or"118.5"is refused, never rounded. The SDK helpersamount()andquantity()write them for you. - A field the API does not know is refused (
FIELD_UNKNOWN), so a misspelt field cannot drop out of a tax document. expectedTotalis optional: send the total you expect and a different computed total is refused.- A refusal is 422
DOCUMENT_REFUSEDwithissues: one entry per reason, each with acodeand thepathof the field. Nothing is stored and the key stays free.
Customers
Send customer.externalRef (your own id of the customer: the first use creates the customer, later uses find it) or customer.key (the key Tring returned as customerKey). Without either, every document creates a new customer record.
Delivery
Your system never receives the original. Ask Tring for a personal link and send it to the customer: the first download is the original ("מקור"), later ones are copies.
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": "ישראלה ישראלי" }'The answer holds url and token once. GET /v1/documents/{id}/pdf returns a signed copy for your records; GET /v1/documents/{id}/delivery says whether the customer downloaded the original.
Corrections and cancellation
| Situation | What to do |
|---|---|
| The original has not left the business and the business says it was not yet reported | POST /v1/documents/{id}/cancellation with "declaredUnreported": true |
| A tax invoice (305, 320) after the original left | A credit note: docType 330 with creditedInvoices |
| A receipt after the original left | A cancelling receipt: docType 400 with corrects: { docType: 400, number } |
| A transaction invoice after the original left | A correcting 300 with corrects and effect credit or charge |
A cancellation after the original left answers 409 ORIGINAL_RELEASED, and details.correction names the document to issue instead.
Document design
A business chooses how its documents look: a template, an accent colour, a font, and a footer line. GET /v1/issuers/{issuerId}/design reads the design in force; PUT stores a new version.
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": "תודה שבחרתם בנו",
})- A design applies to documents produced after it. A document already issued keeps its design in every copy.
- Sending the design in force stores nothing and answers
"created": false, so the call is safe to repeat. - Storing needs a key with the scope
businesses; reading needsread. - A design that cannot be stored answers 422
DESIGN_REFUSED;detailsname the field and the reason:unknown,format,contrast(with asuggestionfor the colour),too-long,reserved-word,mixed-word(a Latin letter, digit or symbol between two Hebrew letters),character,long-number.
Errors
Every error has one body: { "error": { "code", "message", "details", "issues"?, "requestId" } }. Match on code. Quote requestId when you report a problem. The full list per operation is in the API reference.