Preparing a Legacy System for Israel Invoice Without Replacing It

An older system that issues invoices does not have to be thrown away to work against the allocation-number service. The gap is almost always a data gap rather than an architectural one: a missing unique identifier, a missing column for the number that comes back, and a missing pause in the flow before printing.

This is a technical description of an architecture and of data fields, not tax, legal or accounting advice.

What the older system is actually missing

Systems built before online invoicing issue a document and print it in the same action. There is no pause between them that waits for an external answer. That structure is what has to be taken apart, and it is also the only part that genuinely touches the old code.

At the data level, these are the columns that are almost always absent from the document record:

• A stable unique identifier for the call, written before the first request rather than generated at print time.
• A column for the allocation number received, separate from the internal document number.
• A call status: not sent, sent, approved, not approved, alternative chosen.
• A timestamp for the last call and an attempt counter.
• The customer's VAT number, populated and well formed, rather than free text sitting inside a name field.

That last one sinks more old databases than anything else, because in many systems the customer's VAT number lives as text beside the name, or does not exist at all. Structural validation of Israeli identifiers before they reach an interface is covered in validating Israeli ID and company numbers in forms.

Can allocation be added without touching the legacy system?

Almost. The practical shape is a separate middle layer between the legacy system and the service, but it cannot be entirely transparent: something has to hold the allocation number and the status, and something has to stop the print. Both of those touch the source system.

What can stay untouched: pricing logic, internal document numbering, reports, and everything around them. The layer reads the document record, builds the request body, calls the service, writes two columns back, and returns a binary answer to the issuing screen.

The order of operations that changes

• The document is saved with its reference number before the call, because per the specification the call is made once the invoice already carries that reference number.
• The request goes out with a unique identifier and the document fields.
• The response is inspected on its output fields, not on the HTTP status code alone.
• The allocation number is stored on the record, and only then is the document printed.
• If no number came back, the screen presents the alternatives and the choice is recorded.

One further separation saves a lot of pain: waiting, retrying and backing off are not the issuing screen's job. If the service is slow, the screen should show a state rather than freeze, and the system should be able to resume from where it stopped.

What happens to Access systems and old files

Older databases add difficulties of their own. Dates stored as free text will not translate into the YYYY-MM-DD format the specification defines for date fields. Numeric values stored as strings will pass or fail schema validation depending on what somebody typed a decade ago. Legacy Hebrew encoding can turn a customer name into noise inside a JSON body.

So the first step is an exceptions report over the existing data, not writing code: how many documents have no customer VAT number, how many dates cannot be parsed, how many amounts are negative in unexpected places. If the system is on its way out anyway, read the Access to web system migration plan before investing in a layer you will discard.

How do you test this without risking real invoices?

The specification defines two environments: a production address and a testing address under tsandbox. The first pass runs against the test environment, using data from the real system but in a separate runtime.

• A completely valid document, to prove authentication and request shape.
• A document with a bad VAT number, to prove the code recognises a content error.
• A negative response, to prove the screen does not print.
• A connection dropped mid-call, to prove the document does not end in an unknown state.
• A repeat call with the same identifier, to prove nothing is duplicated.

What to decide before writing a line of code

Most of these projects stall on operational decisions rather than on integration. Settle them up front, because each one changes the implementation.

• What happens when the service is unreachable: does issuing stop, or continue and get flagged for handling.
• Who in the business is authorised to choose an alternative when no number came back, and what happens when that person is out.
• Whether the new flow applies to every document type or only to some.
• How long the screen waits before showing a message, and how many retries are attempted.
• Who is alerted when documents pile up in a non-final status.

The first decision is the heaviest and it is not an engineering one. A system that stops issuing when the network is down protects data integrity and shuts the counter. A system that continues keeps the business running and creates a queue of documents needing attention. Both are defensible, but one has to be chosen and written down, because otherwise it gets decided in practice by whatever happens to be in the code.

What this does to the detailed VAT report

The new column does not stay inside the system. The specification defines a "short allocation number" - the last nine characters - required on the transaction record in the detailed report, on both the sales and the input side. Every change made in the issuing layer therefore has to reach the code that produces the report file, or you end up with a system that issues correctly and reports partially. Full background on that file is in automating VAT reporting in Israel.

Sources

• Israel Invoice model - API description, Israel Tax Authority (edition 2.0, 7/2024)
• Open API user guide, Israel Tax Authority