# Tring API: full developer documentation Source: https://developers.tring.co.il/en/ (generated from the docs and spec/openapi.json, version 1.0.0). --- # Tring API # Tring API Issue Israeli tax documents from your code: receipts, tax invoices, tax invoice / receipts, credit notes and transaction invoices. Tring computes the amounts and the VAT, numbers the document, signs it and keeps it. Your system sends what was sold or received. ```js import { Tring } from 'tring-sdk'; const tring = new Tring(); // TRING_API_KEY=kbl_test_... const { draft } = await tring.prepareDraft(issuerId, receipt, { idempotencyKey: 'order-1001-receipt' }); const { document } = await tring.confirmDraft(draft.id); ``` ```python from tring_sdk import Tring tring = Tring() # TRING_API_KEY=kbl_test_... draft = tring.prepare_draft(issuer_id, receipt, idempotency_key="order-1001-receipt")["draft"] document = tring.confirm_draft(draft["id"])["document"] ``` ```sh curl -sS -X POST "$TRING_BASE_URL/v1/issuers/$TRING_ISSUER_ID/drafts" \ -H "Authorization: Bearer $TRING_API_KEY" \ -H "Idempotency-Key: order-1001-receipt" \ -H "Content-Type: application/json" --data @receipt.json ``` ## Where to start | Page | What it covers | |---|---| | [Quickstart](quickstart.html) | A sandbox key, install, your first receipt in curl, JavaScript or Python | | [Issuing documents](issuing.html) | Prepare and confirm, the Idempotency-Key, what to do when the outcome is unknown, the five types, corrections | | [Webhooks and events](webhooks.html) | Signed notices when a document is issued or downloaded, checking them, reading events after a gap | | [SDKs](sdks.html) | Configuration, retries, errors, pagination, helpers, webhook signatures | | [AI agents and MCP](ai.html) | Connect Claude Code or Cursor; how issuing stays behind a person's approval | | [API reference](reference.html) | Every operation, its SDK method and its error codes | ## Five rules 1. Issuing is two calls: **prepare** computes a draft and issues nothing; **confirm** issues it. 2. One `Idempotency-Key` per document, made from your order number and stored before the first call. 3. When a confirm gets no answer, send the same confirm again. Never prepare again under a new key. 4. Amounts are text with two decimals (`"118.00"`), quantities with four (`"1.0000"`). 5. Build against the sandbox: its keys start with `kbl_test_`. Production is a new address and a `kbl_live_` key. ## Packages | Package | Install | |---|---| | TypeScript / JavaScript SDK (Node 18+) | `npm install tring-sdk` | | Python SDK (3.9+) | `pip install tring-sdk` | | MCP server for AI agents | `npx -y tring-mcp` | | Local mock of the API | `npx tring-mock-server` | All four are generated from the same [OpenAPI spec](../openapi.json). For AI tools there is [llms.txt](../llms.txt) and [llms-full.txt](../llms-full.txt). --- # Quickstart # Quickstart You will issue a receipt for 118.00 in the sandbox. Sandbox documents carry the line "דוגמה בלבד" and are not tax documents. ## 1. Get a key and a business You need two values: - A sandbox API key. It starts with `kbl_test_`. Keep it in your secret store or in `.env`, never in code. - The id of a business (`issuerId`) that granted your key. `GET /v1/issuers` lists them. No key yet? Run the local mock. It answers like the API, accepts any `kbl_test_` key, and prints the three values to export: ```sh npx tring-mock-server ``` ## 2. Install ```sh npm install tring-sdk ``` ```sh pip install tring-sdk ``` ```sh # curl and jq are enough jq --version ``` ## 3. Set the environment ```sh export TRING_API_KEY=kbl_test_... export TRING_ISSUER_ID=... export TRING_BASE_URL=https://sandbox.tring.co.il # or the address the mock printed ``` The SDKs read these variables. Without `TRING_BASE_URL` they pick the sandbox for a `kbl_test_` key and production for a `kbl_live_` key. ## 4. Issue a receipt ```js // examples/js/quickstart.mjs // 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}`); } ``` ```python // examples/python/quickstart.py """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']}") ``` ```sh // examples/curl/quickstart.sh #!/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 @- < **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](https://tring.co.il/terms.html#fair-use) (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. ```json { "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 | 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. ```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: 'תודה שבחרתם בנו', }); ``` ```python 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 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](reference.html). --- # Webhooks and events # Webhooks and events Tring tells your system when something happens, by a signed HTTPS POST to an address you register. A notice is thin: what happened, when, to which business, and the identifiers. Read the details with your key; that read is also how you know the notice told the truth. ## The events | `type` | When | `data` | |---|---|---| | `document.issued` | A document was issued, through the API or in the portal | `documentId` | | `document.cancelled` | A document was cancelled | `documentId` | | `draft.confirmed` | Your draft became a document | `draftId`, `documentId` | | `draft.expired` | Your draft passed its time unconfirmed | `draftId` | | `delivery.opened` | The page of a personal link was opened for the first time | `documentId`, `linkId` | | `delivery.downloaded` | A file was taken through a link: the original the first time | `documentId`, `linkId`, `deliveryId` | | `consent.changed` | A customer gave or withdrew consent | `customerKey` | | `allocation.received`, `allocation.held`, `allocation.failed` | An allocation number arrived, was held, or was refused | `documentId` | | `transmission.status_changed`, `transmission.failed` | A transmission of the uniform file changed or failed | `exportId` | | `issuer.activated`, `issuer.granted`, `issuer.revoked` | A business was activated, granted your system, or withdrew it | | | `endpoint.test` | Sent by `POST /v1/webhook-endpoints/{id}/test` | `endpointId` | ```json { "id": "0b3c0b6e-35d4-4ab5-9e43-6a3e1f0d6f21", "object": "event", "type": "document.issued", "created": "2026-11-20T09:15:02.418Z", "environment": "sandbox", "issuerId": "8d0f4b5e-0c6b-4c1e-9d56-1f3f8f7a2b10", "data": { "documentId": "d6980f12-1c28-49dd-9449-efde29b023df" } } ``` Headers: `Tring-Signature`, `Tring-Event-Id`, `Tring-Event-Type`, `Tring-Delivery-Id`, `Tring-Delivery-Attempt`. The SDKs type every body (`TringWebhookEvent`, discriminated by `type`). ## Register an address ```js const { endpoint, secret } = await tring.createWebhookEndpoint({ url: 'https://example.com/tring/webhook', eventTypes: ['document.issued', 'delivery.downloaded'], // or ['*'] }); // store `secret` now, like the API key: no later answer holds it await tring.sendWebhookTest(endpoint.id); // posts an endpoint.test notice at once ``` ```python created = tring.create_webhook_endpoint({ "url": "https://example.com/tring/webhook", "eventTypes": ["document.issued", "delivery.downloaded"], }) secret = created["secret"] # store it now: no later answer holds it tring.send_webhook_test(created["endpoint"]["id"]) ``` ```sh curl -sS -X POST "$TRING_BASE_URL/v1/webhook-endpoints" \ -H "Authorization: Bearer $TRING_API_KEY" \ -H "Content-Type: application/json" \ -d '{"url": "https://example.com/tring/webhook", "eventTypes": ["document.issued"]}' ``` The address must be `https` with a public host (the sandbox also allows `http` and your own machine). Registering, changing, rotating and testing need a key with the scope `webhooks`; the reads need `read`. At most 16 addresses. ## Check every notice `Tring-Signature` is `t=,v1=`. `v1` is the lower-case hex HMAC-SHA256 of `.` followed by the raw body, under your secret (the whole `whsec_...` string). Refuse a notice whose `t` is more than 300 seconds from your clock. The SDK helper does all of this, in constant time, and accepts several secrets during a rotation: ```js // examples/js/webhook-handler.mjs // A webhook receiver: check the signature on the raw body, answer 2xx at once, then do the work once per // event id. Works the same in Express (express.raw({ type: 'application/json' })), Next.js route handlers // (await request.arrayBuffer()) and edge runtimes. // Run: TRING_WEBHOOK_SECRET=whsec_... node webhook-handler.mjs import http from 'node:http'; import { constructWebhookEvent, TringSignatureError } from 'tring-sdk'; // During a rotation put the old and the new secret here: TRING_WEBHOOK_SECRET=old,new const secrets = (process.env.TRING_WEBHOOK_SECRET ?? '').split(',').filter(Boolean); const seen = new Set(); // keep this in your database: a notice can arrive more than once http .createServer(async (req, res) => { const chunks = []; for await (const chunk of req) chunks.push(chunk); let event; try { // the raw bytes: a body parsed and written again would not match the signature event = await constructWebhookEvent({ payload: Buffer.concat(chunks), headers: req.headers, secret: secrets }); } catch (err) { res.writeHead(err instanceof TringSignatureError ? 400 : 500).end(); return; } res.writeHead(204).end(); // answer within 10 seconds, before the work if (seen.has(event.id)) return; seen.add(event.id); // A notice holds identifiers only: read the details with your key, e.g. tring.getDocument(event.data.documentId) console.log(event.type, event.data); }) .listen(Number(process.env.PORT ?? 3000)); ``` ```python from tring_sdk import construct_webhook_event, TringSignatureError # Flask: request.get_data(); Django: request.body; FastAPI: await request.body() try: event = construct_webhook_event(request.get_data(), headers=request.headers, secret=[WEBHOOK_SECRET]) except TringSignatureError: abort(400) # answer 2xx now; do the work once per event["id"] ``` 1. Use the raw body, the bytes as they arrived. A body parsed and written again is not the same bytes. 2. Answer `2xx` within 10 seconds, before doing the work. 3. Keep the event `id` and do nothing twice for one id: a notice can arrive more than once, and in any order. 4. A notice never asks you to issue anything. If you issue because of one, still prepare and confirm under your own Idempotency-Key. ## Retries, rotation, the log A notice not answered `2xx` in 10 seconds is tried again after about 1 minute, 5 minutes, 25 minutes, 2 hours, 10 hours, then every 12 hours, for three days. An address that took nothing for three days is switched off; switch it on again with `updateWebhookEndpoint(id, { enabled: true })`. `rotateWebhookSecret(id, { overlapSeconds: 86400 })` returns a new secret; the old one keeps signing beside it for the overlap, so every notice carries two `v1`. Put both secrets in your receiver, then remove the old one. `{ overlapSeconds: 0 }` ends a leaked secret at once. `listWebhookDeliveries(endpointId)` and `getWebhookDelivery(deliveryId)` show every try (your status, how long, why it failed); `redeliverWebhook(deliveryId)` sends one again with the same event id. ## Reading events after a gap Every event meant for your system is also in `GET /v1/events`, oldest first. Keep the id of the last event you handled and ask for what came after it: ```js let after = lastHandledEventId; for (;;) { const page = await tring.listEvents({ after, limit: 100 }); for (const event of page.items) await handle(event); if (!page.nextCursor) break; after = page.items.at(-1).id; } ``` ```python after = last_handled_event_id while True: page = tring.list_events(after=after, limit=100) for event in page["items"]: handle(event) if not page["nextCursor"]: break after = page["items"][-1]["id"] ``` ## Try it locally The mock sends real signed notices: run `npx tring-mock-server`, register `http://127.0.0.1:3000/` with the handler above running, and issue a receipt from the [quickstart](quickstart.html). --- # SDKs # SDKs Both SDKs are generated from the [OpenAPI spec](../openapi.json): every operation of the API is a method named by its `operationId` (camelCase in TypeScript, snake_case in Python), with the request and answer types of the spec. A thin hand-written layer adds retries, errors and helpers. | | TypeScript / JavaScript | Python | |---|---|---| | Install | `npm install tring-sdk` | `pip install tring-sdk` | | Runtime | Node 18+, Bun, Deno; ESM | 3.9+, sync and async (httpx) | | Client | `new Tring()` | `Tring()` / `AsyncTring()` | ## Configuration ```js import { Tring } from 'tring-sdk'; const tring = new Tring({ apiKey: process.env.TRING_API_KEY, // default: TRING_API_KEY baseUrl: process.env.TRING_BASE_URL, // default: by the key's prefix timeoutMs: 60_000, // one attempt maxRetries: 2, // reads and idempotent requests confirmMaxRetries: 8, // a confirm whose outcome is unknown appInfo: 'my-shop/1.4', // added to the User-Agent }); ``` ```python from tring_sdk import Tring tring = Tring( api_key=None, # default: TRING_API_KEY base_url=None, # default: by the key's prefix timeout=60.0, # one attempt, seconds max_retries=2, # reads and idempotent requests confirm_max_retries=8, # a confirm whose outcome is unknown app_info="my-shop/1.4", # added to the User-Agent ) ``` A `kbl_live_` key against the sandbox address, or a `kbl_test_` key against production, is refused before anything is sent. Printing the client shows the public part of the key only. ## Calling operations ```js const page = await tring.listDocuments(issuerId, { docType: 400, from: '2026-11-01', limit: 50 }); const doc = await tring.getDocument(page.items[0].id); const pdf = await tring.downloadDocument(doc.id); // Uint8Array, a signed copy const link = await tring.createDocumentLink(doc.id, { recipientName: 'ישראלה ישראלי' }); // any operation by name, typed, including ones added after this SDK version const same = await tring.request('listDocuments', { path: { issuerId }, query: { limit: 50 } }); ``` ```python page = tring.list_documents(issuer_id, doc_type=400, from_="2026-11-01", limit=50) doc = tring.get_document(page["items"][0]["id"]) pdf = tring.download_document(doc["id"]) # bytes, a signed copy link = tring.create_document_link(doc["id"], {"recipientName": "ישראלה ישראלי"}) # any operation by name same = tring.request("listDocuments", path={"issuerId": issuer_id}, query={"limit": 50}) ``` Request bodies use the API's field names (`docType`, `documentDate`) in both languages, so the JSON in the docs and in the spec can be pasted as it is. ### Prepare and confirm in one call `issue()` prepares, lets you look at the draft, and confirms. If the key was already used for this request and became a document, it returns that document and issues nothing. ```js const document = await tring.issue(issuerId, body, { idempotencyKey: `order-${order.id}-receipt`, approve: async (draft) => draft.document.amounts.total === order.total, // false: nothing is issued }); ``` ```python document = tring.issue( issuer_id, body, idempotency_key=f"order-{order.id}-receipt", approve=lambda draft: draft["document"]["amounts"]["total"] == order.total, ) ``` ### Sending a file An operation that takes a file (the supplier's receipt of an expense, `putExpenseReceipt`) takes the file itself as the body, not JSON: its bytes, sent with its media type (`image/jpeg`, `image/png` or `application/pdf`, at most 5 MiB). Pass a Buffer, Uint8Array, ArrayBuffer, Blob or File in JavaScript; bytes, a path or a file opened with `"rb"` in Python. The media type is read from the first bytes when you leave it out (`contentType` / `content_type` says it), and the name of a File or a path names the stored file unless `fileName` / `file_name` does. A file whose first bytes are not the media type it was sent as is refused (422 `EXPENSE_REFUSED`, `details.file: "file-kind"`); the same file again stores nothing (`"replayed": true`). The download (`getExpenseReceipt`) hands back the same bytes. ```js // examples/js/expense-receipt.mjs // Record an expense and attach the supplier's receipt (a JPEG, PNG or PDF), then read the file back. // Run: node expense-receipt.mjs receipt.pdf (reads TRING_API_KEY, TRING_ISSUER_ID and, if set, TRING_BASE_URL) import { readFile } from 'node:fs/promises'; import { basename } from 'node:path'; import { Tring, amount, todayInIsrael } from 'tring-sdk'; const tring = new Tring(); const issuerId = process.env.TRING_ISSUER_ID; const path = process.argv[2] ?? 'receipt.pdf'; const { expense } = await tring.createExpense( issuerId, { date: todayInIsrael(), supplier: 'ספק לדוגמה', amount: amount(118), vat: amount(18), category: 'office' }, { idempotencyKey: 'expense-2026-0042' }, // one key per expense ); // The body is the file itself. Its media type is read from its first bytes; pass { contentType } to say it. const file = await readFile(path); // a Buffer; a Uint8Array, ArrayBuffer, Blob or File works too const { replayed, expense: withFile } = await tring.putExpenseReceipt(issuerId, expense.id, file, { fileName: basename(path) }); console.log(`${replayed ? 'Already attached' : 'Attached'}: ${withFile.receipt.fileName} (${withFile.receipt.mediaType}, ${withFile.receipt.sizeBytes} bytes)`); const back = await tring.getExpenseReceipt(issuerId, expense.id); // Uint8Array, byte for byte as sent console.log(`Read back ${back.length} bytes, ${Buffer.from(back).equals(file) ? 'the same file' : 'a different file'}`); ``` ```python // examples/python/expense-receipt.py # Record an expense and attach the supplier's receipt (a JPEG, PNG or PDF), then read the file back. # Run: python expense-receipt.py receipt.pdf (reads TRING_API_KEY, TRING_ISSUER_ID and, if set, TRING_BASE_URL) import os import sys from pathlib import Path from tring_sdk import Tring, amount, today_in_israel tring = Tring() issuer_id = os.environ["TRING_ISSUER_ID"] path = Path(sys.argv[1] if len(sys.argv) > 1 else "receipt.pdf") expense = tring.create_expense( issuer_id, {"date": today_in_israel(), "supplier": "ספק לדוגמה", "amount": amount(118), "vat": amount(18), "category": "office"}, idempotency_key="expense-2026-0042", # one key per expense )["expense"] # The body is the file itself: a path (its name names the file), bytes, or a file opened with "rb". # Its media type is read from its first bytes; pass content_type= to say it. attached = tring.put_expense_receipt(issuer_id, expense["id"], path) receipt = attached["expense"]["receipt"] assert receipt is not None print(f"{'Already attached' if attached['replayed'] else 'Attached'}: {receipt['fileName']} ({receipt['mediaType']}, {receipt['sizeBytes']} bytes)") back = tring.get_expense_receipt(issuer_id, expense["id"]) # bytes, byte for byte as sent print(f"Read back {len(back)} bytes, {'the same file' if back == path.read_bytes() else 'a different file'}") ``` ## Retries Each operation has a retry policy, generated from the spec (`spec/retry-policy.json` and the `x-tring-retry` field): | Policy | Operations | Sent again after | |---|---|---| | safe | every GET | a lost answer, 502, 503, 504, 429 | | idempotent | prepare, add a business, uniform export, backups, allocation number | a lost answer, 504 `OUTCOME_UNKNOWN`, 429; with the same Idempotency-Key | | confirm | confirm | the same, until the outcome is known (`confirmMaxRetries`) | | unsafe | links, emails, cancellation, consent | 429 and 503 `UNAVAILABLE` only: requests the service did not process | The wait follows `Retry-After` when the answer has one, otherwise 0.5 s doubled each time with jitter. ## Errors | Class (JS / Python) | When | |---|---| | `TringApiError` | The API answered with its error body. `code`, `status`, `details`, `issues`, `requestId`, `retryAfter`. | | `TringOutcomeUnknownError` | A confirm still has no known outcome. Confirm `draftId` again later; never prepare again. | | `TringConnectionError` | No answer, and the request was not safe to send again. `mayHaveTakenEffect` tells whether it changes something. | | `TringConfigError` | Wrong use, such as a missing key or Idempotency-Key. Nothing was sent. | | `TringApprovalDeclinedError` | `issue()` was declined by `approve`. Nothing was issued. | | `TringSignatureError` | A webhook signature did not verify. | ```js import { isTringApiError } from 'tring-sdk'; try { await tring.prepareDraft(issuerId, body, { idempotencyKey }); } catch (err) { if (isTringApiError(err, 'DOCUMENT_REFUSED')) { for (const issue of err.issues) console.log(issue.code, issue.path); } else throw err; } ``` ```python from tring_sdk import TringApiError try: tring.prepare_draft(issuer_id, body, idempotency_key=key) except TringApiError as err: if err.code != "DOCUMENT_REFUSED": raise for issue in err.issues: print(issue["code"], issue["path"]) ``` ## Pagination ```js for await (const doc of tring.paginate((cursor) => tring.listDocuments(issuerId, { cursor }))) { console.log(doc.number, doc.total); } ``` ```python for doc in tring.paginate(lambda cursor: tring.list_documents(issuer_id, cursor=cursor)): print(doc["number"], doc["total"]) ``` ## Helpers | JS | Python | Does | |---|---|---| | `amount(118)` | `amount(118)` | `"118.00"`; refuses more than two decimals instead of rounding | | `quantity(2)` | `quantity(2)` | `"2.0000"` | | `todayInIsrael()` | `today_in_israel()` | today's date in Asia/Jerusalem, `"YYYY-MM-DD"` | | `idempotencyKey('order', 1001, 400)` | `idempotency_key("order", 1001, 400)` | `"order-1001-400"`, checked | | `DocType.Receipt` | `DocType.RECEIPT` | 400, and the other types | | `PaymentMethod.BankTransfer` | `PaymentMethod.BANK_TRANSFER` | 4, and the other methods | | `redactKeys(text)` | `redact_keys(text)` | keeps only the public part of any key in a log line | | `fileMediaType(bytes)` | `file_media_type(data)` | the media type the first bytes of a file say (`application/pdf`, `image/jpeg`, `image/png`), as the API reads it; null / None otherwise | ## Webhook signatures Check the signature on the raw body before you act on a notice. The helpers follow the service's format: `Tring-Signature: t=,v1=`, HMAC-SHA256 of `.` and the raw bytes, two `v1` during a rotation, 300 seconds of tolerance. The events, registering an address and retries are on [Webhooks and events](webhooks.html). ```js // examples/js/webhook-handler.mjs // A webhook receiver: check the signature on the raw body, answer 2xx at once, then do the work once per // event id. Works the same in Express (express.raw({ type: 'application/json' })), Next.js route handlers // (await request.arrayBuffer()) and edge runtimes. // Run: TRING_WEBHOOK_SECRET=whsec_... node webhook-handler.mjs import http from 'node:http'; import { constructWebhookEvent, TringSignatureError } from 'tring-sdk'; // During a rotation put the old and the new secret here: TRING_WEBHOOK_SECRET=old,new const secrets = (process.env.TRING_WEBHOOK_SECRET ?? '').split(',').filter(Boolean); const seen = new Set(); // keep this in your database: a notice can arrive more than once http .createServer(async (req, res) => { const chunks = []; for await (const chunk of req) chunks.push(chunk); let event; try { // the raw bytes: a body parsed and written again would not match the signature event = await constructWebhookEvent({ payload: Buffer.concat(chunks), headers: req.headers, secret: secrets }); } catch (err) { res.writeHead(err instanceof TringSignatureError ? 400 : 500).end(); return; } res.writeHead(204).end(); // answer within 10 seconds, before the work if (seen.has(event.id)) return; seen.add(event.id); // A notice holds identifiers only: read the details with your key, e.g. tring.getDocument(event.data.documentId) console.log(event.type, event.data); }) .listen(Number(process.env.PORT ?? 3000)); ``` ```python from tring_sdk import construct_webhook_event, TringSignatureError # Flask: request.get_data() is the raw body try: event = construct_webhook_event(request.get_data(), headers=request.headers, secret=[WEBHOOK_SECRET]) except TringSignatureError: abort(400) ``` The header name, its parsing and the signed text are a `scheme` option, so a different format is a configuration change: ```js await verifyWebhookSignature({ payload, headers, secret, scheme: { header: 'X-Tring-Hmac', parse: (v) => ({ timestamp: null, signatures: [v] }), signedPayload: (_t, body) => body, encoding: 'base64' }, toleranceSeconds: 0, }); ``` ## Regenerating from the spec The typed parts of both SDKs and of the MCP server come from `spec/openapi.json`: ```sh npm run spec:sync # copy the current openapi.json into spec/ npm run generate # rewrite the generated files npm run generate:check # CI: fails when a generated file or the spec copy is out of date ``` --- # AI agents and MCP # AI agents and MCP The Tring MCP server lets an AI coding agent (Claude Code, Cursor, any MCP client) read your documents and customers and prepare drafts. Issuing is a separate tool that refuses unless the person approved that exact draft. ## Connect Claude Code ```sh claude mcp add tring --env TRING_API_KEY=kbl_test_... --env TRING_ISSUER_ID=... -- npx -y tring-mcp ``` ```json // examples/claude-code/.mcp.json { "mcpServers": { "tring": { "command": "npx", "args": ["-y", "tring-mcp"], "env": { "TRING_API_KEY": "${TRING_API_KEY}", "TRING_ISSUER_ID": "${TRING_ISSUER_ID}" } } } } ``` With `.mcp.json` in the project, the key comes from your shell (`${TRING_API_KEY}`), so the file can be committed without it. Keep issuing behind a question in `.claude/settings.json`: ```json // examples/claude-code/.claude/settings.json { "permissions": { "allow": [ "mcp__tring__tring_status", "mcp__tring__tring_list_businesses", "mcp__tring__tring_get_business", "mcp__tring__tring_list_documents", "mcp__tring__tring_get_document", "mcp__tring__tring_list_customers", "mcp__tring__tring_get_customer", "mcp__tring__tring_get_reference", "mcp__tring__tring_get_draft", "mcp__tring__tring_prepare_draft", "mcp__tring__tring_preview_draft", "mcp__tring__tring_get_expense_receipt" ], "ask": ["mcp__tring__tring_confirm_draft"] } } ``` ## Connect Cursor Save as `.cursor/mcp.json` in the project, or `~/.cursor/mcp.json` for every project: ```json // examples/cursor/mcp.json { "mcpServers": { "tring": { "command": "npx", "args": ["-y", "tring-mcp"], "env": { "TRING_API_KEY": "${env:TRING_API_KEY}", "TRING_ISSUER_ID": "${env:TRING_ISSUER_ID}" } } } } ``` ## Environment | Variable | | |---|---| | `TRING_API_KEY` | Required. A sandbox key, `kbl_test_...` | | `TRING_ISSUER_ID` | The business the tools use when no `issuer_id` is given | | `TRING_BASE_URL` | The API address; default the sandbox. The local mock works too. | | `TRING_MCP_ALLOW_LIVE` | `1` allows a production key. Without it a `kbl_live_` key is refused and nothing is sent. | ## Key scopes Every API key holds scopes, and every operation names the one it needs (the [API reference](reference.html) shows it). Give the agent's key only what it needs: | Scope | Lets the agent | |---|---| | `read` | Every list and read tool (events, webhook log, design), and the draft preview | | `issue` | `tring_prepare_draft` and `tring_confirm_draft` | | `expenses` | `tring_attach_expense_receipt` | | `finance` | `tring_get_expense_receipt` | A key with `read` alone keeps the agent read-only: a prepare answers 403 `KEY_SCOPE_MISSING` and nothing is done. Keys can also be limited to your networks (`KEY_ADDRESS_NOT_ALLOWED` otherwise). ## Tools | Tool | Does | Changes anything | |---|---|---| | `tring_status` | Environment, address, key id, default business | No | | `tring_list_businesses`, `tring_get_business` | Businesses this key may act for | No | | `tring_list_documents`, `tring_get_document` | Documents, with filters | No | | `tring_list_customers`, `tring_get_customer` | Customers | No | | `tring_get_reference` | VAT rate and allocation threshold | No | | `tring_list_events` | Events since a given id (document.issued, delivery.downloaded, ...) | No | | `tring_list_webhook_endpoints`, `tring_list_webhook_deliveries` | Webhook addresses and their delivery log, for debugging a receiver; never a secret | No | | `tring_get_document_design` | The design documents are produced with | No | | `tring_prepare_draft` | Computes a draft. Issues nothing. | Stores a draft | | `tring_get_draft`, `tring_preview_draft` | Reads a draft; writes its PDF preview to a private local file | No | | `tring_attach_expense_receipt` | Attaches the supplier's receipt (JPEG, PNG or PDF, from a local path or base64) to an expense; anything else by its first bytes is refused before it is sent | Replaces the file in force | | `tring_get_expense_receipt` | Writes the receipt of an expense, byte for byte, to a private local file | No | | `tring_confirm_draft` | **Issues** the document | Yes, for good | ## How issuing stays safe 1. The agent calls `tring_prepare_draft`. The answer is the draft in plain text (type, customer, lines, total) and the instruction to show it and ask. 2. The person reads it and says yes. 3. The agent calls `tring_confirm_draft` with the `draft_id`, the `approved_total` and `approved_doc_type` the person saw, and their words of approval. The server reads the draft again and refuses when the total or the type differ. Nothing is issued then. 4. Confirming twice returns the same document. If the outcome is unknown, the tool says to confirm the same draft again, never to prepare a new one. The tool's description tells the agent that it creates a legally binding tax document and may run only after the person approved the exact draft. The `ask` rule above makes Claude Code show you every call to it, whatever the agent decides. The server never writes the key to a tool result or its log (anything that looks like a key is reduced to its public part), and writes previews only to a directory private to its process. ## Prompts that work - "List the receipts we issued this week and their total." - "Prepare a receipt for order 1042: 350.00 by bank transfer from דנה כהן, customer ref crm-88. Show it to me before issuing." - "Write a Next.js route that issues a tax invoice / receipt after a successful payment, using tring-sdk, with the order id as the idempotency key." ## Docs for agents [llms.txt](../llms.txt) is a short index with the rules an agent must keep; [llms-full.txt](../llms-full.txt) is these docs as one file. Point your agent at them, or add to your project instructions (`CLAUDE.md`, `.cursorrules`): ```text Tring API docs: https://developers.tring.co.il/llms-full.txt Use tring-sdk (TypeScript) or tring-sdk (Python, import tring_sdk). Prepare, show the draft, confirm only after approval. One Idempotency-Key per document; after an unknown outcome confirm again, never prepare again. ``` --- # API reference # API reference Generated from [openapi.json](../openapi.json), which holds every field and answer. Base address: `https://sandbox.tring.co.il` for the sandbox. Every request carries `Authorization: Bearer `. ## Businesses ### The businesses of this client ```http GET /v1/issuers ``` | SDK | | |---|---| | JavaScript | `tring.listIssuers()` | | Python | `tring.list_issuers()` | | Key scope | `read` | | Parameters | `limit`, `cursor` | | Errors | `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `REQUEST_INVALID` 422, `RATE_LIMITED` 429, `INTERNAL` 500, `UNAVAILABLE` 503 | Every business that gives this client a standing grant, and every business this client added that is still "invited". ### Add a business ```http POST /v1/issuers ``` | SDK | | |---|---| | JavaScript | `tring.createIssuer()` | | Python | `tring.create_issuer()` | | Key scope | `businesses` | | Body | `CreateIssuerRequest` | | Errors | `MALFORMED_JSON` 400, `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `ISSUER_ALREADY_EXISTS` 409, `ISSUER_REGISTERED` 409, `PAYLOAD_TOO_LARGE` 413, `UNSUPPORTED_MEDIA_TYPE` 415, `REQUEST_INVALID` 422, `RATE_LIMITED` 429, `INTERNAL` 500, `UNAVAILABLE` 503 | Adds a business with its details. It joins as "invited" and can issue nothing. Its owner then activates it in the product's own portal and gives this client permission to act for it; until then every issuing call for it answers 404. Sending the same request again returns the same business ("replayed": true); the same registration number with other details, or a business this client already acts for, answers ISSUER_ALREADY_EXISTS. One registration number is one business, whoever adds it: when the register already holds the number for a business this client may not act for, nothing is added, the answer is ISSUER_REGISTERED, and the owner of that business is asked in the portal to give this client permission. Text is cleaned of invisible characters and repeated spaces before it is stored. ### One business ```http GET /v1/issuers/{issuerId} ``` | SDK | | |---|---| | JavaScript | `tring.getIssuer()` | | Python | `tring.get_issuer()` | | Key scope | `read` | | Errors | `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `RATE_LIMITED` 429, `INTERNAL` 500, `UNAVAILABLE` 503 | The business with the version of its details in force today. "status" and "granted" say whether documents can be issued for it. ### The design of the business's documents ```http GET /v1/issuers/{issuerId}/design ``` | SDK | | |---|---| | JavaScript | `tring.getDocumentDesign()` | | Python | `tring.get_document_design()` | | Key scope | `read` | | Errors | `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `ISSUER_NOT_ACTIVE` 409, `RATE_LIMITED` 429, `INTERNAL` 500, `UNAVAILABLE` 503 | The template, accent colour, typeface and line of the business that its next document is printed with. The elements the law asks a document to show are printed by the service in every template and are not part of a design. ### Choose the design of the business's documents ```http PUT /v1/issuers/{issuerId}/design ``` | SDK | | |---|---| | JavaScript | `tring.putDocumentDesign()` | | Python | `tring.put_document_design()` | | Key scope | `businesses` | | Body | JSON | | Errors | `MALFORMED_JSON` 400, `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `ISSUER_NOT_ACTIVE` 409, `PAYLOAD_TOO_LARGE` 413, `UNSUPPORTED_MEDIA_TYPE` 415, `DESIGN_REFUSED` 422, `REQUEST_INVALID` 422, `RATE_LIMITED` 429, `INTERNAL` 500, `UNAVAILABLE` 503 | Stores the design as a new version. It applies to the documents produced after it; a document already issued keeps the design it was produced with, in every copy. Sending the design in force stores nothing and answers it with "created": false. A design that cannot be stored answers DESIGN_REFUSED, and details name the field and the reason ("unknown", "format", "contrast" with a "suggestion", "too-long", "reserved-word" with the "word", "mixed-word" for a Latin letter, digit or symbol between two Hebrew letters, "character", "long-number"). ## Issuing ### Prepare a document ```http POST /v1/issuers/{issuerId}/drafts ``` | SDK | | |---|---| | JavaScript | `tring.prepareDraft()` | | Python | `tring.prepare_draft()` | | Key scope | `issue` | | Parameters | `Idempotency-Key` (required) | | Body | `PrepareRequest` | | Errors | `MALFORMED_JSON` 400, `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `IDEMPOTENCY_KEY_REUSED` 409, `ISSUER_NOT_ACTIVE` 409, `DRAFT_ABANDONED` 410, `DRAFT_EXPIRED` 410, `PAYLOAD_TOO_LARGE` 413, `UNSUPPORTED_MEDIA_TYPE` 415, `DOCUMENT_REFUSED` 422, `IDEMPOTENCY_KEY_INVALID` 422, `REQUEST_INVALID` 422, `RATE_LIMITED` 429, `INTERNAL` 500, `REGISTRATION_NOT_IN_FORCE` 503, `UNAVAILABLE` 503 | Step one of two. The server validates the request, computes every amount and stores a pending draft that expires. Nothing is issued and no number is taken. The answer is the computed document and its warnings: show it, or its preview, before confirming. ### Read a draft ```http GET /v1/drafts/{draftId} ``` | SDK | | |---|---| | JavaScript | `tring.getDraft()` | | Python | `tring.get_draft()` | | Key scope | `read` | | Errors | `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `ISSUER_NOT_ACTIVE` 409, `RATE_LIMITED` 429, `DRAFT_CORRUPT` 500, `INTERNAL` 500, `UNAVAILABLE` 503 | A draft this client prepared, in whatever state it is. A draft that became a document names it in "documentId". ### The preview of a draft, as a PDF ```http GET /v1/drafts/{draftId}/preview ``` | SDK | | |---|---| | JavaScript | `tring.previewDraft()` | | Python | `tring.preview_draft()` | | Key scope | `read` | | Errors | `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `DRAFT_CONFIRMED` 409, `DRAFT_STALE` 409, `ISSUER_NOT_ACTIVE` 409, `DRAFT_ABANDONED` 410, `DRAFT_EXPIRED` 410, `RATE_LIMITED` 429, `DRAFT_CORRUPT` 500, `INTERNAL` 500, `RENDER_FAILED` 500, `UNAVAILABLE` 503 | The page the document would be, marked "טיוטה", with no number [DOC-05]. It is not a document, is not signed and is never stored. Only a pending draft has a preview. ### Confirm a draft: issue the document ```http POST /v1/drafts/{draftId}/confirm ``` | SDK | | |---|---| | JavaScript | `tring.confirmDraft()` | | Python | `tring.confirm_draft()` | | Key scope | `issue` | | Errors | `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `DRAFT_STALE` 409, `ISSUER_NOT_ACTIVE` 409, `DRAFT_ABANDONED` 410, `DRAFT_EXPIRED` 410, `DOCUMENT_REFUSED` 422, `RATE_LIMITED` 429, `COUNTER_MISSING` 500, `DATABASE_REFUSED` 500, `DRAFT_CORRUPT` 500, `INTERNAL` 500, `RENDER_FAILED` 500, `SIGNATURE_NOT_VERIFIED` 500, `SIGNING_FAILED` 500, `SIGNING_KEY_UNAVAILABLE` 500, `ISSUE_TIMEOUT` 503, `REGISTRATION_NOT_IN_FORCE` 503, `UNAVAILABLE` 503, `OUTCOME_UNKNOWN` 504 | Step two of two, and the only call that issues. In one transaction the draft becomes a document: it takes the next number of its series, its original is rendered, signed with the key of the business and stored. The request has no body. ## Documents ### The documents of a business ```http GET /v1/issuers/{issuerId}/documents ``` | SDK | | |---|---| | JavaScript | `tring.listDocuments()` | | Python | `tring.list_documents()` | | Key scope | `read` | | Parameters | `limit`, `cursor`, `from`, `to`, `docType`, `customerKey`, `number` | | Errors | `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `ISSUER_NOT_ACTIVE` 409, `REQUEST_INVALID` 422, `RATE_LIMITED` 429, `INTERNAL` 500, `UNAVAILABLE` 503 | Issued documents, newest first by record number. Every filter is optional; they narrow together. Each call is written to the audit log of the business. ### One document ```http GET /v1/documents/{documentId} ``` | SDK | | |---|---| | JavaScript | `tring.getDocument()` | | Python | `tring.get_document()` | | Key scope | `read` | | Errors | `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `RATE_LIMITED` 429, `INTERNAL` 500, `UNAVAILABLE` 503 | The document as the permanent file holds it. Each read is written to the audit log of the business. ### The file of a document, as a PDF ```http GET /v1/documents/{documentId}/pdf ``` | SDK | | |---|---| | JavaScript | `tring.downloadDocument()` | | Python | `tring.download_document()` | | Key scope | `read` | | Parameters | `form` | | Errors | `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `ISSUER_NOT_ACTIVE` 409, `REQUEST_INVALID` 422, `RATE_LIMITED` 429, `DATABASE_REFUSED` 500, `INTERNAL` 500, `RENDER_FAILED` 500, `SIGNATURE_NOT_VERIFIED` 500, `SIGNING_FAILED` 500, `SIGNING_KEY_UNAVAILABLE` 500, `DELIVER_TIMEOUT` 503, `UNAVAILABLE` 503, `OUTCOME_UNKNOWN` 504 | A client system is handed a "העתק" (copy) of the document, or the "מבוטל" view of a cancelled one, signed with the key of the business. It is never handed the "מקור": the original leaves once, to the customer, through a link or on paper. "form" chooses the computerized form (default) or the paper form, for printing. ### Record the allocation number of a tax invoice ```http POST /v1/documents/{documentId}/allocation-number ``` | SDK | | |---|---| | JavaScript | `tring.recordAllocationNumber()` | | Python | `tring.record_allocation_number()` | | Key scope | `issue` | | Body | JSON | | Errors | `MALFORMED_JSON` 400, `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `ISSUER_NOT_ACTIVE` 409, `DOCUMENT_CANCELLED` 410, `PAYLOAD_TOO_LARGE` 413, `UNSUPPORTED_MEDIA_TYPE` 415, `INPUT_INVALID` 422, `REQUEST_INVALID` 422, `RATE_LIMITED` 429, `DATABASE_REFUSED` 500, `INTERNAL` 500, `DELIVER_TIMEOUT` 503, `UNAVAILABLE` 503, `OUTCOME_UNKNOWN` 504 | The business obtained an allocation number from the Tax Authority itself and the client system passes it on [ALC-05, ALC-06]. This service does not ask the Authority for a number. The number is recorded once, beside the document, and the document itself does not change: every copy rendered from then on prints it under "הקצאה מספר:", and so does the "מקור" while it has not left the business [ALC-08]. A document of type 305, 320 or 330 takes a number; a receipt and a transaction invoice never do. ## Delivery ### The links of a document ```http GET /v1/documents/{documentId}/links ``` | SDK | | |---|---| | JavaScript | `tring.listDocumentLinks()` | | Python | `tring.list_document_links()` | | Key scope | `read` | | Errors | `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `ISSUER_NOT_ACTIVE` 409, `RATE_LIMITED` 429, `INTERNAL` 500, `UNAVAILABLE` 503 | Every link that was made for the document, oldest first, with its state. Never a token. Each call is written to the audit log of the business. ### Make a personal link for the recipient of a document ```http POST /v1/documents/{documentId}/links ``` | SDK | | |---|---| | JavaScript | `tring.createDocumentLink()` | | Python | `tring.create_document_link()` | | Key scope | `delivery` | | Body | `CreateLinkRequest` | | Errors | `MALFORMED_JSON` 400, `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `ALLOCATION_NUMBER_REQUIRED` 409, `CONSENT_WITHDRAWN` 409, `ISSUER_NOT_ACTIVE` 409, `PAYMENT_MEANS_NOT_ALLOWED` 409, `DOCUMENT_CANCELLED` 410, `PAYLOAD_TOO_LARGE` 413, `UNSUPPORTED_MEDIA_TYPE` 415, `INPUT_INVALID` 422, `REQUEST_INVALID` 422, `RATE_LIMITED` 429, `INTERNAL` 500, `MAILER_NOT_CONFIGURED` 501, `UNAVAILABLE` 503 | Makes a link through which the customer of the document opens a page of the issuing business and downloads the document. Opening the page hands out nothing; the recipient presses a button. The first download is the "מקור" and every later one a "העתק". A recipient who has not yet consented to computerized documents of this business is asked on the page, before any download. ### Revoke a link ```http POST /v1/issuers/{issuerId}/links/{linkId}/revocation ``` | SDK | | |---|---| | JavaScript | `tring.revokeLink()` | | Python | `tring.revoke_link()` | | Key scope | `delivery` | | Errors | `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `ISSUER_NOT_ACTIVE` 409, `RATE_LIMITED` 429, `INTERNAL` 500, `UNAVAILABLE` 503 | From this moment the link answers its holder like a link that never existed. Repeating is safe: a link that was already revoked stays as it is and "alreadyRevoked" is true. The request has no body. ### Ask the product to email a link ```http POST /v1/issuers/{issuerId}/links/{linkId}/email ``` | SDK | | |---|---| | JavaScript | `tring.sendLinkEmail()` | | Python | `tring.send_link_email()` | | Key scope | `delivery` | | Body | JSON | | Errors | `MALFORMED_JSON` 400, `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `CONSENT_WITHDRAWN` 409, `ISSUER_NOT_ACTIVE` 409, `LINK_NOT_ACTIVE` 409, `PAYMENT_MEANS_NOT_ALLOWED` 409, `DOCUMENT_CANCELLED` 410, `PAYLOAD_TOO_LARGE` 413, `UNSUPPORTED_MEDIA_TYPE` 415, `INPUT_INVALID` 422, `REQUEST_INVALID` 422, `RATE_LIMITED` 429, `INTERNAL` 500, `MAILER_NOT_CONFIGURED` 501, `MAIL_FAILED` 502, `UNAVAILABLE` 503, `MAIL_OUTCOME_UNKNOWN` 504 | Sends an existing link by email, in the name of the business. The token is stored nowhere, so the caller hands back the token it received when the link was made. The address is "to", or the address the link was made for. The message carries the link and never the file [STO-01]. ### The consent of a customer ```http GET /v1/issuers/{issuerId}/customers/{customerKey}/consent ``` | SDK | | |---|---| | JavaScript | `tring.getConsent()` | | Python | `tring.get_consent()` | | Key scope | `read` | | Errors | `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `ISSUER_NOT_ACTIVE` 409, `RATE_LIMITED` 429, `INTERNAL` 500, `UNAVAILABLE` 503 | Whether a consent of this customer toward this business stands, whether the last word was a withdrawal, and every record that led there [SIG-13]. ### Report a consent the client system collected ```http POST /v1/issuers/{issuerId}/customers/{customerKey}/consent ``` | SDK | | |---|---| | JavaScript | `tring.reportConsent()` | | Python | `tring.report_consent()` | | Key scope | `delivery` | | Body | `ReportConsentRequest` | | Errors | `MALFORMED_JSON` 400, `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `ISSUER_NOT_ACTIVE` 409, `PAYLOAD_TOO_LARGE` 413, `UNSUPPORTED_MEDIA_TYPE` 415, `INPUT_INVALID` 422, `REQUEST_INVALID` 422, `RATE_LIMITED` 429, `INTERNAL` 500, `UNAVAILABLE` 503 | Records that this customer consented to receive computerized documents of this business, when the client system collected the consent itself [SIG-11, SIG-12]. The exact words the customer agreed to and the evidence are required and are kept with the moment and the request. A consent given on the page of a link needs no report: the page records it. Every report is a new record. ### Report that a customer withdrew consent ```http POST /v1/issuers/{issuerId}/customers/{customerKey}/consent/withdrawal ``` | SDK | | |---|---| | JavaScript | `tring.withdrawConsent()` | | Python | `tring.withdraw_consent()` | | Key scope | `delivery` | | Body | `WithdrawConsentRequest` | | Errors | `MALFORMED_JSON` 400, `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `ISSUER_NOT_ACTIVE` 409, `PAYLOAD_TOO_LARGE` 413, `UNSUPPORTED_MEDIA_TYPE` 415, `INPUT_INVALID` 422, `REQUEST_INVALID` 422, `RATE_LIMITED` 429, `INTERNAL` 500, `UNAVAILABLE` 503 | Records a withdrawal the client system received. From this moment the product sends this customer nothing more of this business: no download through any link, no new link, no email [SIG-14]. Repeating is safe: a withdrawal that is already in force adds no record ("recorded": false, 200). The body may be left out. ### Cancel a document ```http POST /v1/documents/{documentId}/cancellation ``` | SDK | | |---|---| | JavaScript | `tring.cancelDocument()` | | Python | `tring.cancel_document()` | | Key scope | `issue` | | Body | `CancelRequest` | | Errors | `MALFORMED_JSON` 400, `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `ALREADY_CANCELLED` 409, `CORRECTION_NOT_CANCELLABLE` 409, `DOCUMENT_REFERENCED` 409, `ISSUER_NOT_ACTIVE` 409, `ORIGINAL_RELEASED` 409, `PAYLOAD_TOO_LARGE` 413, `UNSUPPORTED_MEDIA_TYPE` 415, `DECLARATION_REQUIRED` 422, `INPUT_INVALID` 422, `REQUEST_INVALID` 422, `RATE_LIMITED` 429, `DATABASE_REFUSED` 500, `INTERNAL` 500, `DELIVER_TIMEOUT` 503, `UNAVAILABLE` 503, `OUTCOME_UNKNOWN` 504 | A document can be cancelled only while its "מקור" has not left the business, and only with the statement of the business that it was not yet reported [DOC-54]. The document keeps its number and its record; from then on only its "מבוטל" view is rendered, and nothing of it is sent to anyone. Nothing is deleted. ### What happened to a document after it was issued ```http GET /v1/documents/{documentId}/delivery ``` | SDK | | |---|---| | JavaScript | `tring.getDeliveryRecord()` | | Python | `tring.get_delivery_record()` | | Key scope | `read` | | Errors | `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `ISSUER_NOT_ACTIVE` 409, `RATE_LIMITED` 429, `INTERNAL` 500, `UNAVAILABLE` 503 | The links of the document (never their tokens), the messages that carried them and what became of each, every file that was handed out and to whom, when the "מקור" left the business, and the cancellation [SIG-17]. Each read is written to the audit log of the business. ## Customers ### The customers of a business ```http GET /v1/issuers/{issuerId}/customers ``` | SDK | | |---|---| | JavaScript | `tring.listCustomers()` | | Python | `tring.list_customers()` | | Key scope | `read` | | Parameters | `limit`, `cursor`, `externalRef` | | Errors | `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `ISSUER_NOT_ACTIVE` 409, `REQUEST_INVALID` 422, `RATE_LIMITED` 429, `INTERNAL` 500, `UNAVAILABLE` 503 | In the order of their keys. "externalRef" finds the customer this client created under that reference. ### One customer ```http GET /v1/issuers/{issuerId}/customers/{customerKey} ``` | SDK | | |---|---| | JavaScript | `tring.getCustomer()` | | Python | `tring.get_customer()` | | Key scope | `read` | | Errors | `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `ISSUER_NOT_ACTIVE` 409, `RATE_LIMITED` 429, `INTERNAL` 500, `UNAVAILABLE` 503 | The record of the customer as it stands now. A document carries its own copy of the details as they were printed. ## Uniform file ### The stored productions of a business ```http GET /v1/issuers/{issuerId}/uniform-exports ``` | SDK | | |---|---| | JavaScript | `tring.listUniformExports()` | | Python | `tring.list_uniform_exports()` | | Key scope | `read` | | Parameters | `limit`, `cursor` | | Errors | `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `ISSUER_NOT_ACTIVE` 409, `REQUEST_INVALID` 422, `RATE_LIMITED` 429, `INTERNAL` 500, `UNAVAILABLE` 503 | Newest first. What each production is, without its files. ### Produce the uniform-structure files for a date range ```http POST /v1/issuers/{issuerId}/uniform-exports ``` | SDK | | |---|---| | JavaScript | `tring.produceUniformExport()` | | Python | `tring.produce_uniform_export()` | | Key scope | `records` | | Parameters | `Idempotency-Key` (required) | | Body | JSON | | Errors | `MALFORMED_JSON` 400, `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `DEALER_NUMBER_CHANGED_IN_RANGE` 409, `IDEMPOTENCY_KEY_REUSED` 409, `ISSUER_NOT_ACTIVE` 409, `PAYLOAD_TOO_LARGE` 413, `UNSUPPORTED_MEDIA_TYPE` 415, `IDEMPOTENCY_KEY_INVALID` 422, `INVALID_INPUT` 422, `REQUEST_INVALID` 422, `VALUE_REFUSED` 422, `RATE_LIMITED` 429, `CONSISTENCY_CHECK_FAILED` 500, `INTERNAL` 500, `DIRECTORY_UNAVAILABLE` 503, `UNAVAILABLE` 503 | Reads the permanent file of the business in one snapshot, writes INI.TXT and BKMVDATA.TXT, checks them, and stores the production. The answer describes the production and carries the two reports of the specification; the files themselves are the download of the production. ### The files of a stored production, as one ZIP ```http GET /v1/issuers/{issuerId}/uniform-exports/{exportId}/download ``` | SDK | | |---|---| | JavaScript | `tring.downloadUniformExport()` | | Python | `tring.download_uniform_export()` | | Key scope | `read` | | Errors | `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `ISSUER_NOT_ACTIVE` 409, `RATE_LIMITED` 429, `INTERNAL` 500, `STORED_PRODUCTION_DAMAGED` 500, `UNAVAILABLE` 503 | The directory tree of the specification in one download: OPENFRMT/.//INI.TXT and BKMVDATA.zip, byte for byte as they were produced. The stored bytes are checked against their hashes before they leave. Each download is written to the audit log of the business. ### The 2.6 report: documents per type in a date range ```http GET /v1/issuers/{issuerId}/reports/documents ``` | SDK | | |---|---| | JavaScript | `tring.getDocumentsReport()` | | Python | `tring.get_documents_report()` | | Key scope | `read` | | Parameters | `from` (required), `to` (required), `format` | | Errors | `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `ISSUER_NOT_ACTIVE` 409, `INVALID_INPUT` 422, `REQUEST_INVALID` 422, `RATE_LIMITED` 429, `INTERNAL` 500, `UNAVAILABLE` 503 | Count and total of the documents of every type in the range, without producing files. "format" chooses JSON (default), the plain text form, or one self-contained HTML page. Each call is written to the audit log of the business. ## Transmission ### Where the transmission of a production stands ```http GET /v1/issuers/{issuerId}/uniform-exports/{exportId}/transmission ``` | SDK | | |---|---| | JavaScript | `tring.getTransmission()` | | Python | `tring.get_transmission()` | | Key scope | `read` | | Errors | `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `ISSUER_NOT_ACTIVE` 409, `RATE_LIMITED` 429, `INTERNAL` 500, `AUTHORITY_NOT_CONFIGURED` 503, `UNAVAILABLE` 503 | Read from what was recorded: the status, what to do next, both files, the words of the Authority about a refusal or a rejection [TRX-18], and every step in order. Nothing is asked of the Authority by this call. ### Transmit a stored production to the Tax Authority, or go on with its transmission ```http POST /v1/issuers/{issuerId}/uniform-exports/{exportId}/transmission ``` | SDK | | |---|---| | JavaScript | `tring.transmitUniformExport()` | | Python | `tring.transmit_uniform_export()` | | Key scope | `records` | | Errors | `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `ISSUER_NOT_ACTIVE` 409, `SIGN_IN_REQUIRED` 409, `TRANSMISSION_IN_PROGRESS` 409, `AUTHORITY_REFUSED` 422, `FILE_TOO_LARGE` 422, `RATE_LIMITED` 429, `INTERNAL` 500, `STORED_PRODUCTION_DAMAGED` 500, `TOKEN_STORE_UNREADABLE` 500, `AUTHORITY_FAILED` 502, `AUTHORITY_NOT_CONFIGURED` 503, `AUTHORITY_UNREACHABLE` 503, `PRODUCTION_SWITCHED_OFF` 503, `UNAVAILABLE` 503 | Call it right after a production was stored [TRX-01]. The same call is "send", "send again" and "continue": what it does is decided from what was recorded. Never sent, or the last attempt ended: a new attempt. An attempt that has its links and not yet both files: it goes on from the file that is missing. Both files uploaded: nothing is sent again and the status is asked. Approved: nothing is requested. The stored files are sent as they are; nothing is ever produced again [TRX-18]. ### Ask the Tax Authority for the status of a transmitted production ```http POST /v1/issuers/{issuerId}/uniform-exports/{exportId}/transmission/status ``` | SDK | | |---|---| | JavaScript | `tring.checkTransmissionStatus()` | | Python | `tring.check_transmission_status()` | | Key scope | `records` | | Errors | `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `ISSUER_NOT_ACTIVE` 409, `SIGN_IN_REQUIRED` 409, `TRANSMISSION_IN_PROGRESS` 409, `AUTHORITY_REFUSED` 422, `RATE_LIMITED` 429, `INTERNAL` 500, `TOKEN_STORE_UNREADABLE` 500, `AUTHORITY_FAILED` 502, `AUTHORITY_NOT_CONFIGURED` 503, `AUTHORITY_UNREACHABLE` 503, `PRODUCTION_SWITCHED_OFF` 503, `UNAVAILABLE` 503 | For a production whose two files were uploaded and that is not yet approved or rejected: asks the status service again and records its answer [TRX-11, TRX-12]. For a production that is not at that point nothing is requested and its state comes back. The service also asks by itself from time to time; this call is for a caller that wants the answer now. ### Whether a business is connected to the Tax Authority ```http GET /v1/issuers/{issuerId}/authority-connection ``` | SDK | | |---|---| | JavaScript | `tring.getAuthorityConnection()` | | Python | `tring.get_authority_connection()` | | Key scope | `read` | | Errors | `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `ISSUER_NOT_ACTIVE` 409, `RATE_LIMITED` 429, `INTERNAL` 500, `AUTHORITY_NOT_CONFIGURED` 503, `UNAVAILABLE` 503 | The allocation numbers and the checks of a received invoice need the long connection of the business: its owner signs in at the Tax Authority once, in the portal of the product, and again before the permission ends (three months). This call tells whether that connection stands and by when a new sign-in is needed. Sending a uniform file needs a second, short connection whose sign-in lasts two hours, made in the portal when the file is sent; this call does not describe it, and the state of a transmission says "sign-in" when it is needed. It never returns a token, and there is no call that takes one. ## Allocation ### Where the allocation number of a document stands ```http GET /v1/documents/{documentId}/allocation ``` | SDK | | |---|---| | JavaScript | `tring.getAllocation()` | | Python | `tring.get_allocation()` | | Key scope | `read` | | Errors | `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `ISSUER_NOT_ACTIVE` 409, `RATE_LIMITED` 429, `INTERNAL` 500, `AUTHORITY_NOT_CONFIGURED` 503, `UNAVAILABLE` 503 | Read from what was recorded: whether the law requires a number, the number and its nine rightmost digits [ALC-09], a holding of the Authority and the alternatives after it, the choice and whether it was reported, the error list of the Authority word for word [ALC-15], and every request in order. Nothing is asked of the Authority by this call. ### Ask the Tax Authority for the allocation number of a tax invoice ```http POST /v1/documents/{documentId}/allocation ``` | SDK | | |---|---| | JavaScript | `tring.requestAllocationNumber()` | | Python | `tring.request_allocation_number()` | | Key scope | `issue` | | Body | JSON | | Errors | `MALFORMED_JSON` 400, `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `ALLOCATION_IN_PROGRESS` 409, `ISSUER_NOT_ACTIVE` 409, `SIGN_IN_REQUIRED` 409, `DOCUMENT_CANCELLED` 410, `PAYLOAD_TOO_LARGE` 413, `UNSUPPORTED_MEDIA_TYPE` 415, `AUTHORITY_REFUSED` 422, `INPUT_INVALID` 422, `REQUEST_INVALID` 422, `RATE_LIMITED` 429, `INTERNAL` 500, `TOKEN_STORE_UNREADABLE` 500, `AUTHORITY_FAILED` 502, `AUTHORITY_NOT_CONFIGURED` 503, `AUTHORITY_UNREACHABLE` 503, `PRODUCTION_SWITCHED_OFF` 503, `UNAVAILABLE` 503 | For an issued tax invoice (305, 320) of a business whose owner signed in at the Tax Authority in the portal of the product [ALC-11, ALC-19]. Also for a transaction invoice (300) of a licensed dealer that corrects nothing: it is asked about as the preliminary document "חשבון עסקה/פרופורמה" (code 332) whose "אישור הקצאה" the buyer may check before paying; the number is printed on it as "אישור הקצאה מספר:" with the sentence "לא ניתן לקזז מס תשומות בגין מסמך זה", and a held one offers every alternative but a reverse charge [ALC-25]. A tax invoice that names such a transaction invoice among its related documents is tied to it on its first request (action 4, the invoice_id of the preliminary document), as long as the tax invoices tied to it do not pass its amount without VAT together. The request carries the number and the amounts of the document as they stand in the permanent file; the caller sends nothing of them. ### Report what the business chose after the Tax Authority held its invoice ```http POST /v1/documents/{documentId}/allocation-decision ``` | SDK | | |---|---| | JavaScript | `tring.reportAllocationDecision()` | | Python | `tring.report_allocation_decision()` | | Key scope | `issue` | | Body | JSON | | Errors | `MALFORMED_JSON` 400, `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `ALLOCATION_IN_PROGRESS` 409, `ISSUER_NOT_ACTIVE` 409, `SIGN_IN_REQUIRED` 409, `PAYLOAD_TOO_LARGE` 413, `UNSUPPORTED_MEDIA_TYPE` 415, `AUTHORITY_REFUSED` 422, `INPUT_INVALID` 422, `REQUEST_INVALID` 422, `RATE_LIMITED` 429, `DATABASE_REFUSED` 500, `INTERNAL` 500, `RENDER_FAILED` 500, `SIGNATURE_NOT_VERIFIED` 500, `SIGNING_FAILED` 500, `SIGNING_KEY_UNAVAILABLE` 500, `TOKEN_STORE_UNREADABLE` 500, `AUTHORITY_FAILED` 502, `ALLOCATE_TIMEOUT` 503, `AUTHORITY_NOT_CONFIGURED` 503, `AUTHORITY_UNREACHABLE` 503, `PRODUCTION_SWITCHED_OFF` 503, `UNAVAILABLE` 503, `OUTCOME_UNKNOWN` 504 | Only the business chooses; the client system passes the choice on [ALC-21]. It is stored first and then reported to the Authority, so a report that met a fault is not lost: state.decision.report is "pending", the service sends it again by itself, and the same call may be repeated. A call that answers AUTHORITY_UNREACHABLE or AUTHORITY_FAILED has stored the choice all the same: read the state. The same choice sent twice stores one row. ### Ask the Tax Authority for the allocation numbers of several invoices in one request ```http POST /v1/issuers/{issuerId}/allocation-requests ``` | SDK | | |---|---| | JavaScript | `tring.requestAllocationNumbers()` | | Python | `tring.request_allocation_numbers()` | | Key scope | `issue` | | Body | JSON | | Errors | `MALFORMED_JSON` 400, `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `ALLOCATION_IN_PROGRESS` 409, `ISSUER_NOT_ACTIVE` 409, `SIGN_IN_REQUIRED` 409, `PAYLOAD_TOO_LARGE` 413, `UNSUPPORTED_MEDIA_TYPE` 415, `AUTHORITY_REFUSED` 422, `INPUT_INVALID` 422, `REQUEST_INVALID` 422, `RATE_LIMITED` 429, `INTERNAL` 500, `TOKEN_STORE_UNREADABLE` 500, `AUTHORITY_FAILED` 502, `AUTHORITY_NOT_CONFIGURED` 503, `AUTHORITY_UNREACHABLE` 503, `PRODUCTION_SWITCHED_OFF` 503, `UNAVAILABLE` 503 | Up to 100 issued documents of the business in one request to the MultiApproval service of the Authority (edition 2.0, 2.5 to 2.7) [ALC-26]: tax invoices, and transaction invoices asked about as preliminary documents. Each document is checked as the call for one document checks it, and one that cannot travel is answered for in its item without stopping the others (a document that has its number answers sent false with no error). Every document that travelled is recorded as if it had been asked about alone, and what the answer says of it is acted on in the same way: a number is stored, with the further original; a holding offers the four alternatives in its state; wrong data is the error AUTHORITY_REFUSED of its item. An invoice the answer refuses for its data is corrected and asked about again by itself, with the call for one document, as the Authority instructs; one the answer leaves out, and every invoice of a request that met a fault, is asked about again by itself by the service, with the same invoice_id. ### The amount above which a tax invoice needs an allocation number, as the Tax Authority states it ```http GET /v1/issuers/{issuerId}/allocation-minimum-amount ``` | SDK | | |---|---| | JavaScript | `tring.readAllocationMinimumAmount()` | | Python | `tring.read_allocation_minimum_amount()` | | Key scope | `read` | | Parameters | `date` | | Errors | `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `ALLOCATION_IN_PROGRESS` 409, `ISSUER_NOT_ACTIVE` 409, `SIGN_IN_REQUIRED` 409, `AUTHORITY_REFUSED` 422, `INPUT_INVALID` 422, `REQUEST_INVALID` 422, `RATE_LIMITED` 429, `INTERNAL` 500, `TOKEN_STORE_UNREADABLE` 500, `AUTHORITY_FAILED` 502, `AUTHORITY_NOT_CONFIGURED` 503, `AUTHORITY_UNREACHABLE` 503, `PRODUCTION_SWITCHED_OFF` 503, `UNAVAILABLE` 503 | Asks the MinimumAmount service of the Authority (addendum 8.2025 to edition 2.0) for a date, with the connection of the business, and sets its answer beside the amount this product holds for that date [ALC-17, ALC-02]. The service answers a VAT amount ("סכום המע"מ המינימלי המחייב הקצאת חשבונית"; its example, 3600 in 2025, is 18% of the 20,000 of that year): impliedThreshold is that VAT turned into the amount without VAT by the rate in force on the date. The product's own table, which rests on the law, stays the one that decides whether a number is required; agrees false says that the two differ, for the operator to look at. Nothing is stored in the table by this call. ### The details of a received invoice, by the allocation number printed on it ```http POST /v1/issuers/{issuerId}/received-invoices/details ``` | SDK | | |---|---| | JavaScript | `tring.lookupReceivedInvoice()` | | Python | `tring.lookup_received_invoice()` | | Key scope | `read` | | Body | JSON | | Errors | `MALFORMED_JSON` 400, `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `ALLOCATION_IN_PROGRESS` 409, `ISSUER_NOT_ACTIVE` 409, `SIGN_IN_REQUIRED` 409, `PAYLOAD_TOO_LARGE` 413, `UNSUPPORTED_MEDIA_TYPE` 415, `AUTHORITY_REFUSED` 422, `INPUT_INVALID` 422, `REQUEST_INVALID` 422, `RATE_LIMITED` 429, `INTERNAL` 500, `TOKEN_STORE_UNREADABLE` 500, `AUTHORITY_FAILED` 502, `AUTHORITY_NOT_CONFIGURED` 503, `AUTHORITY_UNREACHABLE` 503, `PRODUCTION_SWITCHED_OFF` 503, `UNAVAILABLE` 503 | For a business that received a tax invoice: asks invoice-information/details of the Authority (version 2, addendum 6.2026) with the connection of the business, which asks as the buyer [ALC-20]. The allocation number may be the whole one or its nine rightmost digits. found false: the Authority holds no invoice with this number from this supplier to this business (code 472). Nothing is stored beside an audit row. ### The allocation number of a received invoice, by its details ```http POST /v1/issuers/{issuerId}/received-invoices/confirmation-number ``` | SDK | | |---|---| | JavaScript | `tring.lookupReceivedConfirmationNumber()` | | Python | `tring.lookup_received_confirmation_number()` | | Key scope | `read` | | Body | JSON | | Errors | `MALFORMED_JSON` 400, `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `ALLOCATION_IN_PROGRESS` 409, `ISSUER_NOT_ACTIVE` 409, `SIGN_IN_REQUIRED` 409, `PAYLOAD_TOO_LARGE` 413, `UNSUPPORTED_MEDIA_TYPE` 415, `AUTHORITY_REFUSED` 422, `INPUT_INVALID` 422, `REQUEST_INVALID` 422, `RATE_LIMITED` 429, `INTERNAL` 500, `TOKEN_STORE_UNREADABLE` 500, `AUTHORITY_FAILED` 502, `AUTHORITY_NOT_CONFIGURED` 503, `AUTHORITY_UNREACHABLE` 503, `PRODUCTION_SWITCHED_OFF` 503, `UNAVAILABLE` 503 | For a business that received a tax invoice without a number, or wants to check the one on it: asks invoice-information/confirmationNumber of the Authority (version 2, addendum 6.2026) with the connection of the business, as the buyer, with the amounts and the date printed on the invoice [ALC-20]. found false: the Authority holds no such invoice (code 472). ## Backup ### The backups of a business ```http GET /v1/issuers/{issuerId}/backups ``` | SDK | | |---|---| | JavaScript | `tring.listBackups()` | | Python | `tring.list_backups()` | | Key scope | `read` | | Errors | `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `ISSUER_NOT_ACTIVE` 409, `RATE_LIMITED` 429, `INTERNAL` 500, `UNAVAILABLE` 503 | The record of every backup that was made of the business, newest first: its date, how far the permanent file reached, and whether the business took its files. At most the newest 100. ### Start a backup of a business now ```http POST /v1/issuers/{issuerId}/backups ``` | SDK | | |---|---| | JavaScript | `tring.startBackup()` | | Python | `tring.start_backup()` | | Key scope | `records` | | Errors | `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `BACKUP_IN_PROGRESS` 409, `ISSUER_NOT_ACTIVE` 409, `BACKUP_LIMIT` 429, `RATE_LIMITED` 429, `BACKUP_FAILED` 500, `INTERNAL` 500, `UNAVAILABLE` 503 | Makes a backup of everything the accounts system holds for the business at this moment (its documents with their signed files, its consents, its customers and the other lists, its uniform-structure files) and records its date. The files of the backup are taken by the business itself, in the portal of the product: this API never hands them out. A request sent again within a minute of a finished backup answers 200 with that backup and "repeated": true, so a request whose answer was lost can simply be sent again. A business makes at most three backups on request in 24 hours (BACKUP_LIMIT). ## Finances ### Income, expenses and profit of a year ```http GET /v1/issuers/{issuerId}/finance ``` | SDK | | |---|---| | JavaScript | `tring.getFinanceYear()` | | Python | `tring.get_finance_year()` | | Key scope | `finance` | | Parameters | `year` (required) | | Errors | `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `ISSUER_NOT_ACTIVE` 409, `REQUEST_INVALID` 422, `RATE_LIMITED` 429, `INTERNAL` 500, `UNAVAILABLE` 503 | The year as the portal's screen "כספים" shows it: the three sums, the twelve months, the income by customer and the expenses by kind, and the years that hold anything. Income is read from the documents the business issued and nothing of them changes. Each call is written to the audit log of the business: the answer holds the names of customers and their sums. ### The expenses of a business ```http GET /v1/issuers/{issuerId}/expenses ``` | SDK | | |---|---| | JavaScript | `tring.listExpenses()` | | Python | `tring.list_expenses()` | | Key scope | `finance` | | Parameters | `limit`, `cursor`, `year`, `month`, `category` | | Errors | `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `ISSUER_NOT_ACTIVE` 409, `REQUEST_INVALID` 422, `RATE_LIMITED` 429, `INTERNAL` 500, `UNAVAILABLE` 503 | Newest first, by the date of the expense. A removed expense is never listed. "month" needs "year". ### Record an expense ```http POST /v1/issuers/{issuerId}/expenses ``` | SDK | | |---|---| | JavaScript | `tring.createExpense()` | | Python | `tring.create_expense()` | | Key scope | `expenses` | | Parameters | `Idempotency-Key` (required) | | Body | `ExpenseRequest` | | Errors | `MALFORMED_JSON` 400, `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `IDEMPOTENCY_KEY_REUSED` 409, `ISSUER_NOT_ACTIVE` 409, `EXPENSE_REMOVED` 410, `PAYLOAD_TOO_LARGE` 413, `UNSUPPORTED_MEDIA_TYPE` 415, `EXPENSE_REFUSED` 422, `IDEMPOTENCY_KEY_INVALID` 422, `REQUEST_INVALID` 422, `RATE_LIMITED` 429, `INTERNAL` 500, `UNAVAILABLE` 503 | Records an expense of the business for the owner's own view of income and profit. It enters no document, series, uniform file or transmission. Each field is checked as the portal checks it; a refusal names every field at fault (EXPENSE_REFUSED) and stores nothing. ### One expense ```http GET /v1/issuers/{issuerId}/expenses/{expenseId} ``` | SDK | | |---|---| | JavaScript | `tring.getExpense()` | | Python | `tring.get_expense()` | | Key scope | `finance` | | Errors | `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `ISSUER_NOT_ACTIVE` 409, `RATE_LIMITED` 429, `INTERNAL` 500, `UNAVAILABLE` 503 | An expense as it stands now. A removed expense is not found. ### Correct an expense ```http PATCH /v1/issuers/{issuerId}/expenses/{expenseId} ``` | SDK | | |---|---| | JavaScript | `tring.updateExpense()` | | Python | `tring.update_expense()` | | Key scope | `expenses` | | Body | `ExpenseChange` | | Errors | `MALFORMED_JSON` 400, `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `ISSUER_NOT_ACTIVE` 409, `PAYLOAD_TOO_LARGE` 413, `UNSUPPORTED_MEDIA_TYPE` 415, `EXPENSE_REFUSED` 422, `REQUEST_INVALID` 422, `RATE_LIMITED` 429, `INTERNAL` 500, `UNAVAILABLE` 503 | Changes the fields sent and keeps the others; "note": null removes the note. The whole expense, as it would stand, is checked again. Sent twice, the same change is the same expense: the second answers "replayed": true and changes nothing. A removed expense is not found. ### Remove an expense ```http DELETE /v1/issuers/{issuerId}/expenses/{expenseId} ``` | SDK | | |---|---| | JavaScript | `tring.removeExpense()` | | Python | `tring.remove_expense()` | | Key scope | `expenses` | | Errors | `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `ISSUER_NOT_ACTIVE` 409, `RATE_LIMITED` 429, `INTERNAL` 500, `UNAVAILABLE` 503 | The expense is shown nowhere and counted in no total from now on. Its row is kept, with the moment and the client system that removed it, and nothing deletes it; a removal is final. Sent again, the answer is the same removal ("replayed": true) and nothing changes. ### The file of the receipt ```http GET /v1/issuers/{issuerId}/expenses/{expenseId}/receipt ``` | SDK | | |---|---| | JavaScript | `tring.getExpenseReceipt()` | | Python | `tring.get_expense_receipt()` | | Key scope | `finance` | | Errors | `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `ISSUER_NOT_ACTIVE` 409, `RATE_LIMITED` 429, `INTERNAL` 500, `UNAVAILABLE` 503 | The file of the supplier's receipt in force, byte for byte as it was sent. Each download is written to the audit log of the business. An expense without a file, and a removed expense, are not found. ### Attach the file of the receipt ```http PUT /v1/issuers/{issuerId}/expenses/{expenseId}/receipt ``` | SDK | | |---|---| | JavaScript | `tring.putExpenseReceipt()` | | Python | `tring.put_expense_receipt()` | | Key scope | `expenses` | | Parameters | `fileName` | | Body | The file itself, raw bytes, with its media type: `application/pdf`, `image/jpeg`, `image/png` | | Errors | `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `ISSUER_NOT_ACTIVE` 409, `PAYLOAD_TOO_LARGE` 413, `UNSUPPORTED_MEDIA_TYPE` 415, `EXPENSE_REFUSED` 422, `REQUEST_INVALID` 422, `RATE_LIMITED` 429, `INTERNAL` 500, `UNAVAILABLE` 503 | The picture (JPEG, PNG) or PDF of the supplier's receipt, sent as the body itself with its media type, at most 5242880 bytes (5 MiB; larger: PAYLOAD_TOO_LARGE). Its kind is read from its first bytes and must be the media type it was sent as. It takes the place of the file in force; the earlier file is kept and is no longer shown. The same file sent again stores nothing ("replayed": true, 200). ## Register ### The catalog of the register ```http GET /v1/issuers/{issuerId}/pos/items ``` | SDK | | |---|---| | JavaScript | `tring.listPosItems()` | | Python | `tring.list_pos_items()` | | Key scope | `pos` | | Errors | `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `ISSUER_NOT_ACTIVE` 409, `RATE_LIMITED` 429, `INTERNAL` 500, `UNAVAILABLE` 503 | Every item in use, in the order of the tiles. An item taken out of the catalog is not listed. ### Keep an item by its code ```http PUT /v1/issuers/{issuerId}/pos/items/{itemCode} ``` | SDK | | |---|---| | JavaScript | `tring.putPosItem()` | | Python | `tring.put_pos_item()` | | Key scope | `pos` | | Body | `PosItemRequest` | | Errors | `MALFORMED_JSON` 400, `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `ISSUER_NOT_ACTIVE` 409, `PAYLOAD_TOO_LARGE` 413, `UNSUPPORTED_MEDIA_TYPE` 415, `POS_ITEM_REFUSED` 422, `REQUEST_INVALID` 422, `RATE_LIMITED` 429, `INTERNAL` 500, `UNAVAILABLE` 503 | Makes the item of this code (201) or changes it to what was sent (200); the fields left out take their defaults. Sent again with the same body it changes nothing ("replayed": true). A change never reaches a document already issued. Each field is checked as the portal checks it; a refusal names every field at fault (POS_ITEM_REFUSED: required, too-long, invalid, too-many) and stores nothing. At most 500 items in use per business. ### Take an item out of the catalog ```http DELETE /v1/issuers/{issuerId}/pos/items/{itemCode} ``` | SDK | | |---|---| | JavaScript | `tring.removePosItem()` | | Python | `tring.remove_pos_item()` | | Key scope | `pos` | | Errors | `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `ISSUER_NOT_ACTIVE` 409, `RATE_LIMITED` 429, `INTERNAL` 500, `UNAVAILABLE` 503 | The item is archived: no tile, no sale. Its row is kept and nothing deletes it; its code is free for another item. A code with no item in use is not found. ### The registers ```http GET /v1/issuers/{issuerId}/pos/registers ``` | SDK | | |---|---| | JavaScript | `tring.listPosRegisters()` | | Python | `tring.list_pos_registers()` | | Key scope | `pos` | | Errors | `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `ISSUER_NOT_ACTIVE` 409, `RATE_LIMITED` 429, `INTERNAL` 500, `UNAVAILABLE` 503 | The registers in use of the business, oldest first, each with whether a shift is open and the number of its last close. ### The closes of the registers ```http GET /v1/issuers/{issuerId}/pos/closes ``` | SDK | | |---|---| | JavaScript | `tring.listPosCloses()` | | Python | `tring.list_pos_closes()` | | Key scope | `pos` | | Parameters | `registerId` | | Errors | `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `ISSUER_NOT_ACTIVE` 409, `REQUEST_INVALID` 422, `RATE_LIMITED` 429, `INTERNAL` 500, `UNAVAILABLE` 503 | Newest first, at most 200; of one register with "registerId". Each answer is written to the audit log of the business. ### One close ```http GET /v1/issuers/{issuerId}/pos/closes/{closeId} ``` | SDK | | |---|---| | JavaScript | `tring.getPosClose()` | | Python | `tring.get_pos_close()` | | Key scope | `pos` | | Errors | `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `ISSUER_NOT_ACTIVE` 409, `RATE_LIMITED` 429, `INTERNAL` 500, `UNAVAILABLE` 503 | A close with its figures as they were stored. Written to the audit log of the business. ## Reference ### The VAT rate and the allocation amount in force today ```http GET /v1/reference ``` | SDK | | |---|---| | JavaScript | `tring.getReference()` | | Python | `tring.get_reference()` | | Key scope | `read` | | Errors | `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `RATE_LIMITED` 429, `INTERNAL` 500, `UNAVAILABLE` 503 | The standard VAT rate [DOC-61] and the amount above which a tax invoice needs an allocation number [ALC-02], as the server applies them to a document dated today. A caller never sends either: the server fills them. ## Webhooks ### Your webhook addresses ```http GET /v1/webhook-endpoints ``` | SDK | | |---|---| | JavaScript | `tring.listWebhookEndpoints()` | | Python | `tring.list_webhook_endpoints()` | | Key scope | `read` | | Parameters | `includeDeleted` | | Errors | `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `REQUEST_INVALID` 422, `RATE_LIMITED` 429, `INTERNAL` 500, `UNAVAILABLE` 503 | Every address of your system that is not deleted, oldest first; with includeDeleted=true the deleted ones too. ### Register a webhook address ```http POST /v1/webhook-endpoints ``` | SDK | | |---|---| | JavaScript | `tring.createWebhookEndpoint()` | | Python | `tring.create_webhook_endpoint()` | | Key scope | `webhooks` | | Body | `CreateWebhookEndpointRequest` | | Errors | `MALFORMED_JSON` 400, `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `WEBHOOK_ENDPOINT_LIMIT` 409, `PAYLOAD_TOO_LARGE` 413, `UNSUPPORTED_MEDIA_TYPE` 415, `INPUT_INVALID` 422, `REQUEST_INVALID` 422, `RATE_LIMITED` 429, `INTERNAL` 500, `UNAVAILABLE` 503, `WEBHOOKS_NOT_CONFIGURED` 503 | Registers an address of your system to be told of events by a signed HTTPS POST (see the webhooks section of this file, and INTEGRATION 13). The answer holds the signing secret, once. Events are posted from the moment of registration; nothing earlier is sent, and GET /v1/events holds the earlier ones. At most 16 addresses per client system. The address must be https on port 443 or 8443, and its host a public name or address: an address of a private, loopback, link-local or reserved range is refused, also when a name resolves to one later. ### One webhook address ```http GET /v1/webhook-endpoints/{endpointId} ``` | SDK | | |---|---| | JavaScript | `tring.getWebhookEndpoint()` | | Python | `tring.get_webhook_endpoint()` | | Key scope | `read` | | Errors | `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `RATE_LIMITED` 429, `INTERNAL` 500, `UNAVAILABLE` 503 | The address, its state and when its secrets were made and end. Never a secret. ### Change a webhook address ```http POST /v1/webhook-endpoints/{endpointId} ``` | SDK | | |---|---| | JavaScript | `tring.updateWebhookEndpoint()` | | Python | `tring.update_webhook_endpoint()` | | Key scope | `webhooks` | | Body | `UpdateWebhookEndpointRequest` | | Errors | `MALFORMED_JSON` 400, `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `WEBHOOK_ENDPOINT_DELETED` 409, `PAYLOAD_TOO_LARGE` 413, `UNSUPPORTED_MEDIA_TYPE` 415, `INPUT_INVALID` 422, `REQUEST_INVALID` 422, `RATE_LIMITED` 429, `INTERNAL` 500, `UNAVAILABLE` 503, `WEBHOOKS_NOT_CONFIGURED` 503 | Changes the address, its description or the kinds of events it takes, or switches it off ("enabled": false: what waited for it is dropped, and can be sent again by hand from the delivery log) and on again ("enabled": true, also after the service switched it off for failing). What is left out stays. ### Delete a webhook address ```http POST /v1/webhook-endpoints/{endpointId}/deletion ``` | SDK | | |---|---| | JavaScript | `tring.deleteWebhookEndpoint()` | | Python | `tring.delete_webhook_endpoint()` | | Key scope | `webhooks` | | Errors | `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `RATE_LIMITED` 429, `INTERNAL` 500, `UNAVAILABLE` 503 | Deletes the address for good: nothing more is posted to it, what waited is dropped, its secrets stop signing at once. Its delivery log stays readable. Sending it again answers the same. ### Rotate the signing secret ```http POST /v1/webhook-endpoints/{endpointId}/secret-rotation ``` | SDK | | |---|---| | JavaScript | `tring.rotateWebhookSecret()` | | Python | `tring.rotate_webhook_secret()` | | Key scope | `webhooks` | | Body | JSON | | Errors | `MALFORMED_JSON` 400, `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `WEBHOOK_ENDPOINT_DELETED` 409, `PAYLOAD_TOO_LARGE` 413, `UNSUPPORTED_MEDIA_TYPE` 415, `INPUT_INVALID` 422, `REQUEST_INVALID` 422, `RATE_LIMITED` 429, `INTERNAL` 500, `UNAVAILABLE` 503, `WEBHOOKS_NOT_CONFIGURED` 503 | Makes a new signing secret and answers it, once. The secrets that signed until now go on signing beside it for overlapSeconds (24 hours by default): during that time every notice carries two v1 signatures, so your receiver takes the new secret in without missing one. 0 ends the old secrets at once, for a secret that leaked. ### Post a test notice now ```http POST /v1/webhook-endpoints/{endpointId}/test ``` | SDK | | |---|---| | JavaScript | `tring.sendWebhookTest()` | | Python | `tring.send_webhook_test()` | | Key scope | `webhooks` | | Errors | `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `WEBHOOK_ENDPOINT_DELETED` 409, `RATE_LIMITED` 429, `WEBHOOK_TEST_TOO_SOON` 429, `INTERNAL` 500, `UNAVAILABLE` 503, `WEBHOOKS_NOT_CONFIGURED` 503 | Posts an "endpoint.test" notice to the address now, signed like every notice, and answers how it went: whether your address answered 2xx, its status, or why it could not be reached. Use it to try your check of the signature. A switched-off address takes it too. One test per address every 5 seconds, and ten per client system in a minute over all its addresses, counted before the notice leaves. ### The delivery log of an address ```http GET /v1/webhook-endpoints/{endpointId}/deliveries ``` | SDK | | |---|---| | JavaScript | `tring.listWebhookDeliveries()` | | Python | `tring.list_webhook_deliveries()` | | Key scope | `read` | | Parameters | `limit`, `cursor`, `status` | | Errors | `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `INPUT_INVALID` 422, `REQUEST_INVALID` 422, `RATE_LIMITED` 429, `INTERNAL` 500, `UNAVAILABLE` 503 | Every delivery to the address, newest first: the event, where its sending stands, how many tries, the last status and why it failed. status narrows it (for example "failed"). ### One delivery, with every try ```http GET /v1/webhook-deliveries/{deliveryId} ``` | SDK | | |---|---| | JavaScript | `tring.getWebhookDelivery()` | | Python | `tring.get_webhook_delivery()` | | Key scope | `read` | | Errors | `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `RATE_LIMITED` 429, `INTERNAL` 500, `UNAVAILABLE` 503 | The delivery and every try of it: when, the status your address answered, how long it took, and why it failed. The body of your answers is never kept. ### Send a delivery again ```http POST /v1/webhook-deliveries/{deliveryId}/redelivery ``` | SDK | | |---|---| | JavaScript | `tring.redeliverWebhook()` | | Python | `tring.redeliver_webhook()` | | Key scope | `webhooks` | | Errors | `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `WEBHOOK_DELIVERY_PENDING` 409, `WEBHOOK_ENDPOINT_DELETED` 409, `RATE_LIMITED` 429, `INTERNAL` 500, `UNAVAILABLE` 503, `WEBHOOKS_NOT_CONFIGURED` 503 | Sends a delivery that succeeded, failed or was dropped once more, within seconds: one try, the same event and the same event id. It does not count toward switching the address off. Read the delivery to see how it went. A delivery that is still waiting or being sent answers WEBHOOK_DELIVERY_PENDING. ### The events meant for your system ```http GET /v1/events ``` | SDK | | |---|---| | JavaScript | `tring.listEvents()` | | Python | `tring.list_events()` | | Key scope | `read` | | Parameters | `after`, `type`, `issuerId`, `limit` | | Errors | `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `INPUT_INVALID` 422, `REQUEST_INVALID` 422, `RATE_LIMITED` 429, `INTERNAL` 500, `UNAVAILABLE` 503 | The events meant for your system, oldest first: every event of the businesses that give it a standing grant, and those about your system itself. Keep the id of the last event you handled and ask with after=: you miss nothing, also while your address was down or when you have none. Works without any webhook address. ### One event ```http GET /v1/events/{eventId} ``` | SDK | | |---|---| | JavaScript | `tring.getEvent()` | | Python | `tring.get_event()` | | Key scope | `read` | | Errors | `UNAUTHENTICATED` 401, `KEY_ADDRESS_NOT_ALLOWED` 403, `KEY_SCOPE_MISSING` 403, `NOT_FOUND` 404, `RATE_LIMITED` 429, `INTERNAL` 500, `UNAVAILABLE` 503 | The event, when it was meant for your system. A receiver that wants to be sure a notice is true reads the event, or the thing it names, with its own key.