Your accounting software sends an invoice to Jordan’s National Invoicing System (JoFotara) through the API, a response comes back, and a second send may follow if the invoice is rejected or the connection drops. JoFotara logging means that your system keeps a written trace of every one of those steps. It is the tenth instruction in the technical guide issued by the Income and Sales Tax Department (ISTD), which asks for all operations (submission, response and resubmission) to be logged to ensure tracking and auditing.
«تسجيل جميع العمليات (إرسال، استجابة، إعادة إرسال) لضمان التتبع والتدقيق»
ISTD publishes this guide in Arabic only; the English here is our rendering, and the Arabic text is the authority.
The guide asks for three connected things. Your system saves four values for every invoice, which are the ID, the UUID, the QR code and EINV_STATUS. It logs errors in detail internally while showing the user a simplified message. And it logs every submission, response and resubmission. The guide does not say what form the log takes, where it is kept or how long it stays. This article is for anyone building or reviewing the link between an accounting or enterprise resource planning system and JoFotara. It combines the three instructions into one design you can apply, and it keeps what the guide states apart from what we suggest.
What JoFotara logging means
The ten instructions sit on page 104 of the technical guide for integrating with the National Invoicing System through the API, version 1.5, issued on May 12, 2026 by the invoicing affairs directorate of ISTD. The tenth is titled “Audit Trail” (تتبع العمليات). Two earlier instructions in the same table are tied to it, the fifth, titled “storing core data” (تخزين البيانات الأساسية), and the sixth, titled “error management” (إدارة الأخطاء).
In our reading, each of the three answers a different question. The fifth decides what stays saved about an invoice in its latest state. The sixth decides how an error is handled inside the system and in front of the user. The tenth decides that every operation an invoice went through stays recorded in order. The difference between the fifth and the tenth is the difference between a snapshot of the invoice now and its full history. An invoice can end as SUBMITTED after a first rejection and a resend. The four values keep the final result, and the operations log keeps the road that led to it.
This instruction is technical and concerns your linked system. It is separate from the register of sales invoices, paper or computerized, that Article 6 of Regulation No. 34 of 2019 on Organizing and Controlling Invoicing Affairs, as amended, requires, and separate from the period for keeping invoices that Article 8 of the same regulation governs. The technical guide does not tie the tenth instruction to any retention period.
The guide texts the design rests on
Before any design, these are the related instructions from page 104 and what follows from each in a system that sends invoices. The ninth and seventh instructions are included because the ninth governs the time of every logged operation and the seventh governs what must not appear in the clear.
Scroll the table sideways to see the remaining columns
ISTD publishes this guide in Arabic only; the English here is our rendering, and the Arabic text is the authority. The last column is our practical reading of the text, not part of it. For all ten instructions in order, with an explanation of each, see our article JoFotara Guidelines for Linked Systems: All Ten Explained.
The four values to store for every invoice
The values the fifth instruction names do not all come from the same place. Two are generated by your system before sending, and two are returned by JoFotara in the response. Knowing where each comes from decides when it is saved.
Scroll the table sideways to see the remaining columns
In its operating notes the guide says the invoice number in the system is not the ID alone. It is made of the ID and the UUID together as the primary key. It also warns that letting the identifier generate itself without storing it can lead to duplicate invoices when a resend happens, so it must be stored and reused. The practical consequence for logging is that both identifiers must be saved in your system before the first request leaves, not after the response returns. Our article JoFotara UUID: Why It Comes Back With the ID covers this point in detail.
In the same notes the guide adds saving the line item ID of each product as it appeared on the sales invoice, because return invoices are matched on it. The signed invoice that the system returns in the element EINV_SINGED_INVOICE is not among the four values of the fifth instruction, so whether to save it is a design decision that is yours to make.
What your system logs for every submission, response and resubmission
The tenth instruction names three kinds of operation and does not say which fields each log line carries. The table below is therefore a suggestion from us for designing the log line. Every field in it is taken from an element documented in the guide or from the text of an instruction, and its source is shown beside it.
Scroll the table sideways to see the remaining columns
According to the guide, each element of EINV_RESULTS has five fields, type, status, EINV_CODE, EINV_CATEGORY and EINV_MESSAGE. The guide’s own example is an error with the code totalGeneralTaxesAmount, the category invoice and the message Total General Amount is Not Correct. Logging the five fields as they arrived, without shortening, is what makes the log useful in a review, because the message alone may not show which field is meant.
What stays out of the log starts with the linking data. The Client ID and the Secret Key travel in the headers of every request, the seventh instruction asks for them to be protected, and the guide places full responsibility for any unauthorized use on the taxpayer. If you decide to log the request as it went out, our suggestion is to leave the Client-Id and Secret-Key headers out before writing. How to obtain the two values is explained in our article JoFotara Client ID and Secret Key: Device Linking Steps.
Four paths one invoice can take, as they appear in the log
The lines in the log differ with what happens to the invoice after it is sent. The four paths below are built on the statuses and codes the guide documents, and each says what gets logged.
Path one, a submission that ends in acceptance
Your system logs the submission line. The response then returns SUBMITTED in EINV_STATUS, and the response line is logged together with the EINV_RESULTS elements. Reading the status alone does not complete the acceptance, because the guide asks you to check that a QR code is present in the EINV_QR element for the receipt and approval of the invoice to be complete. After that the four values of the invoice are updated and the code is shown on the seller’s invoice.
Path two, a submission that ends in rejection
The response returns NOT_SUBMITTED, its technical status code is not 200, and the QR code, the identifier, the invoice number and the signed invoice all come back as null. This is why the two identifiers in the log are taken from your system and not from the response. The response line is logged with the full ERRORS elements, and the user is shown a simplified message. Once the data is corrected, the invoice is sent again with the same number and the same identifier, as the third instruction asks, so a new line of the resubmission type is logged and the first rejection line is not erased. For the cause of each rejection, see our article JoFotara Error Codes: Why an Invoice Is Rejected and How to Fix It.
A response can also carry a technical status code other than 400, and the guide gives different causes for each. It ties 403 to an error in the Client ID or the Secret Key. It ties 500 to an error in the tax number or the income-source sequence, and less often to an error in the Client ID or the Secret Key, and it also mentions that the tax rate in the XML file may not be among the rates ISTD accepts. Logging the technical status code on every line is what keeps these cases apart from value errors, which code 400 details in EINV_MESSAGE.
Path three, an interruption with no readable response
If the request times out or the connection fails, as with code 504, which the guide ties to the system being unreachable because of the taxpayer’s firewall or the main invoicing site, there is no EINV_STATUS value to log. The submission line with its technical result is enough here, followed by a resubmission line. The eighth instruction says that when a timeout or connection failure happens, the attempt must be repeated without generating a new UUID. The guide does not state how many attempts to make or how long to wait between them.
Path four, a resubmission that returns ALREADY_SUBMITTED
According to the guide, this status means that an invoice with the same number and identifier was sent before, and the original QR code comes back with it. It is the documented way to recover a code that was not saved. This response line is logged like any other, and the returned code is saved in the four values if it was not already there.
The detailed message for the team and the simplified message for the user
The sixth instruction asks for two things at once. The first is a detailed internal record of every error, which is what the developer or the technical solutions provider needs to find the offending element. The second is a simplified message for the end user, the accountant or employee who issued the invoice and does not need an EINV_CODE to know what to fix.
Error messages in the response are written in English, and some contain spelling mistakes, as they appear in the guide. The table below shows messages the guide lists among its code 400 errors, each with a simplified wording we suggest for the user. The suggested wording is ours, and the original message stays in the internal log exactly as it arrived.
To link the two messages, we suggest that the simplified message carry a short reference to the log line, such as the invoice number and the time of the operation, so support can find the full error when a user sends what they saw. Our article on JoFotara error codes shows how to read EINV_MESSAGE and where it sits in the response.
What the technical guide does not specify about logging
The tenth instruction is one line, and the fifth and sixth are two lines each. Someone building a log needs several answers that the guide does not give, and it matters not to fill that gap with rules attributed to ISTD. Version 1.5 of ISTD’s technical guide does not state the following.
- The form of the log and where it is kept. The guide does not say whether the log is a database table, a text file or something else.
- How long the log stays. The guide sets no period for the operations log or the error log, and it does not tie them to the period for keeping invoices.
- Who may read the log. The guide does not state access permissions, although the seventh instruction does require that linking data not appear in the clear.
- The exact time format. The ninth instruction asks for one standard format and names none in its text. The invoice date in
cbc:IssueDateis written asyyyy-mm-dd, as in every XML example in the guide. - The number of retries and the interval between them. The guide specifies that a retry is made without a new identifier, and it does not specify how many retries or when.
- The wording of the simplified message. The guide asks for a simplified message and does not suggest its text.
All of this is a design decision for your business and for the programmer or technical solutions provider you work with. ISTD’s procedures guide for joining the Jordanian National Electronic Invoicing System, 2026 edition, says the taxpayer must coordinate with the system’s programmer or the technical solutions provider it works with to complete the technical requirements. For how responsibility divides between a taxpayer and a provider, see our article JoFotara Solution Provider Responsibility vs the Taxpayer. If you need an official answer on a point the guide leaves open, the guide refers you to the technical support committee for invoicing affairs at ISTD through the ISTD website.
Pre-launch checklist
These are questions a developer or the accountant in charge can use to review the logging design of their system before the first live invoice is sent. Each one rests on an instruction named above.
- Are the invoice number (ID) and the identifier (UUID) saved in your system before the first send?
- Are the four values, the ID, UUID, QR Code and EINV_STATUS, saved for every invoice?
- Is every submission, every response and every resubmission logged on its own line, without erasing what came before?
- Does each line carry the time of the operation in one standard format across your systems?
- Are the technical status code and the value of EINV_STATUS logged together, with the invoice judged by the second?
- Are the EINV_RESULTS elements logged with their five fields as they arrived?
- Does the user see a simplified message instead of the technical one, with a reference that ties it to the log line?
- Is the log free of the Client ID and the Secret Key?
- Does the system check that a QR code is present in EINV_QR before treating the invoice as accepted, and is the code shown on the seller’s invoice?
- Is the invoice sent again with the same number and identifier after a rejection or an interruption?
How Qoyod helps
If your accounting software is the one sending the invoices, it is the software that applies these instructions. Qoyod works on this layer as follows.
- Check before sending. Qoyod checks each invoice at field level as it is created, covering the tax number, the document type and payment method, the General Sales Tax rate and whether the lines are complete, and alerts you to any error before the invoice is sent, to reduce rejections. The pre-send check is an alert, not a guarantee.
- Every invoice’s status in view. ISTD returns the invoice status and any error message, and Qoyod shows them in its status panel, with states that include sent (مرسلة), previously sent (مرسلة مسبقًا) and not sent (لم تُرسل) together with the error message.
- Resending with the same identifier. The status panel lists invoices that were not sent and need to be resent, and when you resend one it keeps the same UUID.
Once ISTD accepts the invoice it returns a QR code, and Qoyod shows that code on the invoice. For a wider view of the system and how to connect your business to it, read our article Jordan’s National E-Invoicing System. The integration itself is described on the page Qoyod’s integration with the National Invoicing System.
E-invoicing and full accounting in one system
Qoyod is integrated with the National Invoicing System (JoFotara). You issue your invoice in Jordanian dinars from Qoyod, it is booked to your ledgers automatically and sent to the system, and once it is accepted it comes back with a QR code from the Income and Sales Tax Department.
Frequently asked questions
What does logging mean in JoFotara?
It refers to the tenth instruction in the technical guide issued by the Income and Sales Tax Department, titled “Audit Trail” (تتبع العمليات). The instruction asks for all operations (submission, response and resubmission) to be logged to ensure tracking and auditing, and it is addressed to the system that sends invoices through the API.
Which values must my system save for each invoice?
The fifth instruction asks for four values, the invoice number (ID), the unique identifier (UUID), the QR code and the invoice status (EINV_STATUS), to ensure tracking and re-retrieval when needed. The operating notes in the guide add saving the line item ID of each product, to be used in return invoices.
Does the guide set a period for keeping the operations log?
The technical guide sets no period for keeping the operations log or the error log. The period for keeping the invoices themselves is a separate matter governed by Article 8 of Regulation No. 34 of 2019 on Organizing and Controlling Invoicing Affairs, as amended, and the guide does not link the two.
Why not show the user the error message exactly as the system returned it?
The sixth instruction asks for errors to be logged in detail inside the system with a simplified message shown to the end user. The original message stays in the log for the technical team, and whoever issued the invoice sees a sentence that tells them what to correct.
Should I log the Client ID and the Secret Key?
We suggest you do not. The seventh instruction asks for the linking data to be protected and not stored in the open inside the code, and the guide places full responsibility for any unauthorized use on the taxpayer, so if you log the request, leave out the two headers that carry those values.
What do I log if the connection drops before a response arrives?
You log the submission line with its technical result, since there is no invoice status value in this case, and then you log the resubmission line. The eighth instruction says to retry without generating a new UUID, and the guide does not state how many attempts to make or the interval between them.
References
- Income and Sales Tax Department (ISTD), technical guide for integrating with the National Invoicing System through the API, version 1.5 (in Arabic), pp. 96 to 102 and 104.
- Income and Sales Tax Department (ISTD), procedures guide for joining the Jordanian National Electronic Invoicing System, 2026 edition (in Arabic).
- Regulation No. 34 of 2019 on Organizing and Controlling Invoicing Affairs, as amended, consolidated text (in Arabic), Articles 6 and 8.
