Integrating With iCount: What to Settle Before You Write Code

iCount is a cloud business-management and invoicing system, and it exposes an API that lets you issue documents and manage customers from another system. This guide does not try to replace the official documentation - and deliberately does not present an exact request shape. The reason follows.

Why this guide gives you no endpoint to copy

I write a lot of integration guides, and there is a recurring pattern in the Israeli market: endpoints, field names and document type codes change between versions, and code copied from a three-year-old article fails in confusing ways.

With iCount this is especially sharp because there are two generations of interface, and they look nothing alike:

This is the main trap. Searching "iCount API" returns a fair amount of code written for the older generation - some of it over a decade old. It looks plausible, it runs, and it fails.

A good indicator: if an example sends a username and password in the request body, it is the old generation. If it sends a token in a header, it matches v3. The iCount community node for n8n, for instance, explicitly requires an API token rather than a company-id/user/password combination - a good sign you are looking in the right direction.

Where to take the request shape from

From iCount's official documentation, opened in a browser. That is where the precise request shape for each operation lives, including required fields and document type codes - against the version running now.

Worth knowing that iCount's documentation is built with tooling that runs JavaScript, so it is not always accessible to automated tools or a plain fetch. That is not a meaningful limitation - but it does mean a person opens the page and copies, rather than a script. On a real project that is five minutes.

The rule I work by: take the request shape from the documentation. Prepare the decisions - which are the real cost - in advance. The rest of this article is about that second part.

The decisions that actually cost time

Once the first call works, the differences between invoicing systems all but vanish. What remains is identical everywhere - and it is what sinks projects.

1. Which document, and when

Tax invoice, combined invoice-receipt, receipt and credit note are not interchangeable. The choice determines when revenue is recognised, which is an accounting question rather than a technical one.

This is the business accountant's decision. If your system decides on its own which document to issue and at what point in the process, that decision needs written sign-off. A developer choosing a document type by reasoning is a risk.

2. The retry problem

This catches almost every first invoicing integration, in every system.

You send a request, the server issues the document, and the connection drops before the response returns. Your code sees a timeout, reads it as failure, and retries - and now there are two tax documents with two sequential numbers. A tax document cannot be deleted; cancellation is an offsetting document, and someone has to handle it by hand.

Three rules:

• A timeout is not a failure - it is an absence of knowledge. Do not retry automatically.
• Store your own unique reference on the order, and before any retry check whether a matching document already exists.
• A missing document beats a duplicate. The first is fixed in a minute; the second needs a cancellation, a paper trail and a conversation with the bookkeeper.

3. VAT and exempt dealers

Whether the amounts you send include VAT - verify against a real document rather than assuming. That is a five-minute check that prevents a month-long correction.

And an exempt dealer does not issue a tax invoice at all. If your system serves more than one dealer type, that changes the document type it issues.

4. Who issues the document

If a payment gateway is also in the picture and configured to issue a document automatically on payment, and your system also issues one, a single transaction produces two tax documents. This is the most common design mistake when payments and accounting touch the same project, and it surfaces at month end. Pick one side and document it before writing a line.

5. Allocation numbers

The Tax Authority requirement applies regardless of which system you chose. Confirm the flow handles it before go-live - see invoice allocation numbers for developers.

Security

The iCount API token authorises issuing tax documents in the business's name. It does not expire on a fixed schedule. So:

• Environment variables or a secrets manager only
• Not in source control, not in logs, and not in any code running in a browser
• If a token leaks - rotate it in the interface, do not "monitor and see"

And persist the full API response even on success: the document id, its sequential number and its link. That is your only evidence when an accounting question arrives six months later.

A test environment

A tax document issued by mistake is not a row you delete - it exists for tax purposes. So ask iCount support explicitly whether a test environment exists and how to get access. It is an entirely fair question, and worth asking before committing to a client timeline rather than after.

In any case: keep the base URL and the token as two separate environment variables, so moving between environments is a configuration change rather than a code change.

Checklist

1. Open the current official documentation and work from it - not from an example you found.
2. Confirm you are on v3, judged by the auth: a token in a header rather than a password in the body.
3. Establish whether there is a test environment before starting.
4. Get written confirmation from the accountant on which documents are issued and when.
5. Verify VAT handling against a real document.
6. Build duplicate protection before issuing the first production document.

For a comparison of the Israeli systems, see the Israeli invoicing API comparison.