Tring for developers עברית

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

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

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}`);
}

Run it twice. The second run prints "Already issued": the same Idempotency-Key with the same request returns the document it became, and nothing new is issued. This is what makes retries safe.

5. What happened

StepCallEffect
PreparePOST /v1/issuers/{issuerId}/draftsChecks the request, computes amounts and VAT, stores a draft for 24 hours. No number is taken.
ConfirmPOST /v1/drafts/{draftId}/confirmTakes the next number, renders, signs and stores the original.

Between the two, show the draft (or its PDF, GET /v1/drafts/{draftId}/preview) to whoever approves it.

Next