Tezga eKasa

Tezga

This connector uses the Tezga eKasa public API (https://pos.narbiz.com/api/integrations), the online fiscal cash register (ESIR with V-PFR) of GoSimple for Serbian companies. It reads the account's fiscal setup and tax labels, the status and fiscal data of issued documents and the company's bank transactions. Issuing a fiscal receipt, cancelling or refunding one, and writing customers and catalogue items are included but installed switched off.

Setup (about 3 minutes)

1. API access is part of the Posao and Biznis plans (or the Enterprise level). On other plans every call answers 402.
2. In Tezga open Podešavanja > Integracije > API ključevi, name a key (e.g. AnythingMCP) and create it. It is shown once; copy it into TEZGA_API_KEY. Keys start with tzg_ followed by 48 hex characters. Use a separate key for this connector so you can pause or delete it alone; you can also bind it to the server's IP addresses there.
3. Install and run tezga_get_account_setup to check the key and see the environment.

The key is sent in the X-Tezga-Api-Key header. Keys rotate every 90 days: Tezga e-mails a reminder on day 76; paste the new key here before the old one is switched off. A read-only key is enough for the read tools; writes with it answer 403.

Environment first: test and production keys look the same; the environment belongs to the account. tezga_get_account_setup returns okruzenje: produkcija (real receipts reported to the Tax Administration), sandbox (official test environment), simulacija (demo, PFR numbers start with MOCK) or nepovezano (no security element, fiscalisation refused). Tell the user which one before any write.

Workflow

• Status of an order: tezga_find_document with your order number (externalId), or tezga_get_document with the Tezga document id. statusDokumenta is nacrt (draft), izdat (issued) or storniran (cancelled); fiskalni holds the PFR number, counter and verification URL, null when not fiscalised; javniPdfUrl opens without login.
• Payments: tezga_list_bank_transactions (smer uplata for incoming, isplata for outgoing, since for a start time).
• Writes (switched off): tezga_issue_receipt (fiscal receipt, proforma or SEF e-invoice; idempotent per externalId), tezga_refund_document (storno or refund, a new document referring to the original), tezga_upsert_customers and tezga_upsert_products (match by PIB/e-mail/name or by item code; nothing is deleted). A fiscal receipt cannot be undone, only refunded, so an admin turns these on deliberately; before each call show the user the lines, amounts and environment and wait for a yes.

Amounts and tax: prices are RSD including VAT (cenaSaPdv). Tax rates are 20, 10, 0 or oslobodjeno. A company outside the VAT system has every line recorded as exempt whatever rate is sent.

Limits: 240 reads and 120 writes per minute per company by default; responses carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, and 429 comes with Retry-After. At most 500 lines per receipt and 500 customers or items per call; body up to 512 KB.

Errors: 401 missing or wrong key. 402 plan without API access or subscription not active (error says which). 403 read-only key used for a write, a till-terminal key, or a request from an IP not on the key's list. 404 the document does not exist in your company. 409 the action is not allowed (not issued, already partly refunded) or the same externalId is being processed. 422 field or rule errors listed in fields. 202 on a write means the document exists but the Tax Administration has not accepted it yet; Tezga retries by itself, do not send it again.