How the WizCloud API works for WizCount: session tokens valid 24 hours, the import endpoint groups, and exporting data through a report you must design first.
Key takeaways
- The official documentation lives at docs.wizcloud.co.il, currently version 2.0.0. This is not an undocumented API you have to extract from support.
- Authentication needs three values from account settings: WizcloudApiServer, WizcloudApiPrivateKey and WizcloudApiDBName.
- One GET to createSession returns a wizAuthToken valid for 24 hours. Everything after that is a POST carrying the token.
- Exporting is not a query. You design a report in the report generator, export it as an External file, and post that file's contents to ExportDataApi/exportData.
- The External file holds a datafile string that encodes the report structure, plus a parameters array, and only the parameters change between runs.
WizCloud publishes a documented API at docs.wizcloud.co.il, and one split in it shapes every integration built on top: imports go to dedicated endpoints per record type, but getting data out runs through a single endpoint that executes a report you designed inside the product first. There is no free-form query.
What WizCloud is, and how it relates to WizCount and Hashavshevet
WizCloud is the cloud environment of Hashavshevet, and WizCount is the English product name for the same family. For integration purposes they are one thing: one API, one documentation set, one grouping of endpoints. Searching for "WizCount API" and for "Hashavshevet cloud API" lands in the same place.
The distinction that does matter is cloud versus the Windows desktop product. The API described here talks to the cloud database and identifies it by a database code passed during authentication. An on-premise Hashavshevet installation is an entirely different integration surface, and teams that conflate the two only discover it when their credentials do nothing.
How does authentication against WizCloud work?
Authentication has two stages, and stage one runs once before everything else. You pull three values from account settings - server name, private key and database code - and issue a GET to the createSession path built from all three. The response carries a wizAuthToken.
That token is valid for 24 hours, which is the real design decision. A process that runs once a day can mint a token on every run. A process that runs every five minutes has to cache the token somewhere shared and refresh it only on expiry, or you are creating sessions for no reason. Caching it in one process's memory breaks the moment you run a second worker.
All three authentication values are secrets in the full sense. A private key committed into a config file is complete access to a client's books.
The endpoint groups and what each one is for
| Group | Example paths | Used for |
|---|---|---|
| session | createSession | Obtaining a wizAuthToken against one database |
| jtransApi | tmpBatch, chkBatch, newBatch, issueBatch | Importing journal transactions in batches, with an error check before commit |
| IndexApi | importIndex | Importing or updating index records |
| invApi | createDoc, getDoc, delDocument, issueDocument | Documents: create, read, delete, issue |
| docsApi | createRecipt, createInvRecipt | Receipts and tax invoice-receipts |
| BankPagesApi | importBankPage | Importing bank statement pages |
| SortCodeApi, TransTypesApi | importSortCodes, importTransTypes | Importing sort codes and transaction types |
| TriggersApi | setURL, deleteURL, updateURL, getURL | Managing the URLs the system calls out to |
| ExportDataApi | exportData | Getting data out, via a report |
The last row is the entire outbound side. Everything above it is inbound.
The jtransApi shape deserves attention on its own: it does not accept a single transaction. It works in batches, with a temporary stage, a check stage and a commit stage. That is precisely the pattern that prevents a half-posted batch, and skipping the check stage means finding your errors after they are already in the ledger. The same "validate before commit" idea shows up in Hashavshevet import errors and reconciliation.
Why can you not just send a query and get rows back?
Because ExportDataApi does not take a query. It takes a report. The process the documentation defines is:
- Open the report generator inside WizCloud and design a report returning exactly the fields you want out.
- Add parameters to the report if the filter changes between runs.
- Choose the External option. A text file is generated and downloaded.
- Copy the datafile value and the parameters array from that file into your request body.
- POST to ExportDataApi/exportData with the token, and receive the rows as JSON.
The practical consequence: every new cut of the data is UI work, not just code. If your system needs three different views, that is three reports and three External files. There is no way to construct a new filter purely on the client side.
The documentation also notes that adding target=pdf to the request returns the report as a PDF rather than the default format. That is useful for attaching to an email, not for processing.
What is inside the External file, field by field
| Field | What it is | Changed at runtime |
|---|---|---|
| datafile | A long encrypted string describing the report structure | No. Copied as-is |
| p_name | The parameter name as the report knows it | No |
| id | The parameter identifier | No |
| type | The value type, for example long or txt | Only if the report changed |
| name | The parameter's Hebrew label, for example קוד מיון | No |
| defVal | The value the report will run with | Yes. This is the only field that genuinely varies |
| opName, opOrigin | The operator and its direction, for example equals or from | Only when needed |
The rule that avoids most bugs: the only field you change between runs is defVal. Any other edit to the parameters array decouples it from the report saved server-side.
The response comes back with a statusCode, a status field whose value is repdata, a report field holding the rows, and an errors field. The error values the documentation lists are OK, Params not found or not match, Data not found, and No Permission. The last three mean completely different things: the first is a bug in your request, the second is a valid report with no matching rows, and the third is a missing permission on the user behind the token.
What actually breaks in a scheduled export
- Someone edited the report in the UI. A column or parameter changed, and the datafile stored in your code no longer matches. What you get back is Params not found or not match, not a notice that a report changed.
- Confusing "no rows" with "failed". A job that treats Data not found as a failure will alert every night that genuinely had no transactions.
- A token expiring mid-run. A job starting at 23:50 with a token that is 23 hours and 58 minutes old dies halfway through.
- Permissions on the user behind the key. No Permission is not a code bug. It is a missing permission inside the account.
- Numbers stored as text. Account numbers and sort codes with leading zeros lose a digit the first time they pass through a spreadsheet on the way somewhere else.
- The wrong database code. One key can reach several companies, and a report run against the wrong one looks completely healthy.
What to have ready before you start building
- Access to the account settings to pull the three authentication values, and a secure place to keep them.
- A decision on who on the client side owns the reports the API executes, and what happens when they edit one.
- An exact list of the data cuts your system needs, because each cut is a separate report.
- A test environment or demo company, so trial transactions never reach real books.
- A decision on how you identify an already-sent record, so a re-run does not create a duplicate document.
Related: Hashavshevet API integration guide, automating business reports.
Sources
Frequently asked questions
How long is a WizCloud wizAuthToken valid?
Per the official documentation, the token returned by createSession is valid for 24 hours. A once-daily job can safely mint a fresh one each run, but a frequent job should cache it between calls and refresh only on expiry, rather than opening a new session for every single request it makes.
Can you export data from WizCloud without designing a report first?
No. The export endpoint, ExportDataApi/exportData, expects a datafile string that is only produced when you design a report in the report generator and choose the External option. There is no free-form query path against the database, so every new data cut begins as UI work.
What is the difference between tmpBatch and issueBatch when importing journal transactions?
They are stages of one process. tmpBatch loads transactions into a temporary area, chkBatch checks them for errors, and issueBatch commits them permanently. The separation exists so a bad batch can be stopped before it enters the books, rather than corrected afterwards from inside the ledger.
What does a No Permission error from exportData mean?
It means the user behind the private key is not authorised for the data the report requests. It is not a problem in your code and not a problem in the datafile string, but a permissions setting inside the account itself, so it is fixed in user settings rather than in the request.
Keep reading
Related service
Dashboards
One screen with the few numbers that actually change a decision.
About the author
Yehonatan Saadia
Freelance automation, web & MVP developer
I'm Yehonatan Saadia, a senior developer who builds business automation, custom websites, and MVPs for small and mid-sized companies across the US, Europe, and Israel. These guides come from real client work, not theory.
Work with meHave a project like this?
Tell me what you're trying to automate or build. I reply within 24 business hours with a few targeted questions, then we walk through it on a free 30-minute call, with no commitment. You come away with a scope, a timeline and a fixed price - or a straight answer that it isn't worth building.