Tring for developers עברית

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

  1. Prepare with POST /v1/issuers/{issuerId}/drafts and an Idempotency-Key header. Tring validates the request, computes every amount and the VAT, and stores a pending draft. Nothing is issued.
  2. 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 sendYou get
The same key with the same requestThe same draft (replayed: true), or the document it became (outcome: "document")
The same key with a different request409 IDEMPOTENCY_KEY_REUSED
A key whose draft expired410 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 confirmMeaningThe SDK
201Issued nowreturns { document, replayed: false }
200Already issued earlierreturns { document, replayed: true }
504 OUTCOME_UNKNOWN, no answer, bare 5xxUnknownsends the same confirm again
503 ISSUE_TIMEOUT, 500 RENDER_FAILED (render-timeout, browser-unavailable)Nothing issued, may repeatsends the same confirm again
409 DRAFT_STALE, 410 DRAFT_EXPIREDNothing issuedthrows; prepare again under a new key
429 RATE_LIMITEDNot processedwaits 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).

WhatPer minute
Requests per API key600
Requests per network address1,200
Failed authentications per address20
Document file downloads per key60

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

docTypeNameHolds
400Receipt (קבלה)payments
305Tax invoice (חשבונית מס)lines
320Tax invoice / receipt (חשבונית מס / קבלה)lines and payments, paid in full
330Credit tax invoice (חשבונית מס זיכוי)lines, creditedInvoices, reason
300Transaction 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.

A tax invoice
{
  "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 helpers amount() and quantity() 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.
  • expectedTotal is optional: send the total you expect and a different computed total is refused.
  • A refusal is 422 DOCUMENT_REFUSED with issues: one entry per reason, each with a code and the path of 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.

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": "ישראלה ישראלי" }'

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

SituationWhat to do
The original has not left the business and the business says it was not yet reportedPOST /v1/documents/{id}/cancellation with "declaredUnreported": true
A tax invoice (305, 320) after the original leftA credit note: docType 330 with creditedInvoices
A receipt after the original leftA cancelling receipt: docType 400 with corrects: { docType: 400, number }
A transaction invoice after the original leftA 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.

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: 'תודה שבחרתם בנו',
});
  • 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 needs read.
  • A design that cannot be stored answers 422 DESIGN_REFUSED; details name the field and the reason: unknown, format, contrast (with a suggestion for 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.