Test JoFotara Submission Without a Sandbox

Before the first submission, anyone building a link between accounting software and the National Invoicing System (JoFotara) asks a practical question. Where do I test? To test JoFotara submission, you will not find a separate environment documented in the technical guide issued by the Income and Sales Tax Department (ISTD). Version 1.5 of the guide gives one address for submitting invoices, and nothing in the guide marks that address as a test address.

The direct answer is that the testing the guide supports happens inside your own system before anything is sent, and that, because the guide documents no test address, the first invoice you send to JoFotara should be treated as a real invoice. This article covers what the guide says about that, what you can check locally from its rules, and what only shows up at the first real submission. Where a step is our suggestion rather than text from the guide, we mark it as a Qoyod suggestion.

The article is for people building a link between an accounting or ERP system and JoFotara, or reviewing an existing link. It therefore describes steps and general structure, and it offers no ready-to-run code.

Test JoFotara submission: what technical guide 1.5 says

The guide gives a single address for submission, POST https://backend.jofotara.gov.jo/core/invoices/. The other addresses in the guide are ISTD’s own website. The guide gives no second address for trial submissions, and no linking credentials set aside for testing.

The screenshots inside the guide show test data from an internal ISTD account. That shows ISTD tests the system internally, but it does not document an environment open to taxpayers or software providers. Do not build your test plan on the assumption that ISTD will give you a test account or a trial address.

You may read in unofficial sources about switching between a test environment and a live one. The technical guide does not support those references, so ask for the official text before you rely on them, or ask ISTD directly as described at the end of this article.

The procedures guide for joining the Jordanian National Electronic Invoicing System puts the job of completing the technical side on the taxpayer. This is its wording.

«يتوجب على المكلف التنسيق مع مبرمج النظام أو مزود الحلول التقنية المعتمد لديه لاستكمال المتطلبات الفنية»

In English, the guide says the taxpayer must coordinate with the system programmer, or with the technical solutions provider the taxpayer works with, to complete the technical requirements. ISTD publishes this guide in Arabic only; the English here is our rendering, and the Arabic text is the authority. We read this to mean that testing the link falls on the taxpayer and whoever builds the link, not on ISTD. This is our reading of the text, not a statement by ISTD.

Why you should treat every invoice you send as a real invoice

JoFotara works on what we call a real-time approval model (our own description, not ISTD wording), so the verdict on an invoice comes back in the response to the request that sent it. If the invoice is accepted, a QR code comes back with it, together with the invoice signed by ISTD. If it is rejected, a list of errors comes back. Our article JoFotara Real-Time Approval: What It Means explains this sequence.

Three things follow from that, and they govern any trial.

1. An accepted invoice is not edited. An invoice is not edited after it is issued. The correction is a return invoice (credit note) on quantities only, which cannot exceed the quantity sold.
2. An invoice identity is never used twice. The primary key of an invoice is its number in cbc:ID together with its unique identifier in cbc:UUID. If you send the same pair again after it was accepted, the status ALREADY_SUBMITTED comes back with the original QR code, and no new invoice is created.
3. A submission carries real linking credentials. Every request carries the Client ID and the Secret Key in its header, and both are tied to a single income-source sequence of the business.

For that reason we advise against sending the system an invoice with no real sale behind it just to test (Qoyod suggestion). An invoice the system accepts is an issued invoice, and the only route the system documents for correcting it is the return invoice.

What you can check before sending and what only sending reveals

The submission errors the guide lists fall into two kinds. Some can be caught inside your system because their rule is written in the guide. Others depend on the business’s data at ISTD, so they only show when the request reaches the system. The table below sets out the split.

The first three rows are the scope of local testing. Pre-submission validation has its own checklist in this series. The last four rows are what the first real submission reveals, and we come back to them in a later section.

Local testing against the guide’s rules

The first instruction in the guide is that the invoice file must conform to the UBL 2.1 standard, and that any structural defect leads to rejection of the invoice. The second is to check the data before sending, to reduce 400 errors. Those two instructions are the basis for the testing you can do without the file leaving your system.

Testing the structure

Check each file that leaves your system against the points below. Each one is a rule written in the guide.

• The file starts with the prolog the guide specifies, and the <Invoice> opening tag, with all its attributes, sits on a single line.
• The cbc:ProfileID field holds reporting:1.0 in every invoice.
• The date is in the format yyyy-mm-dd, as in all the XML examples in the guide.
• The file is encoded in Base64 and placed in a JSON file under the key invoice.
• The request header carries Client-Id, Secret-Key and Content-Type: application/json, and no other header copied from the guide’s code sample.

That last point matters. The code sample in the guide sends a cookie tied to a session at ISTD, so do not carry it into your system. Our article JoFotara UBL 2.1: What It Is and What It Requires explains the structure in more detail.

Testing the arithmetic with the guide’s numbers

We suggest using the figures the guide calculates in its new invoice examples as the expected results for your system’s calculation engine (Qoyod suggestion). You enter the same lines, then compare what your system produces with what the guide shows. These are the three examples as they appear.

• Income invoice (pp. 19 to 21). Two lines. The first is 33 × 2 − 2 = 64 and the second is 10 × 5 − 5 = 45. The total before discount is 116.000, the discount is 7.000, and the amount due is 109.000.
• General sales tax invoice (pp. 40, 43 and 44). One line is 33 × 2 − 2 = 64 at a rate of 7%, with tax of 4.48 and a line total of 68.48. An exempt line of 10 × 5 has category Z and a 0% rate, and its total is 50.00. The total before discount is 116.000, the discount is 2.000, the tax is 4.480, and the amount due is 118.480.
• Special tax invoice (pp. 69 to 71). One line is 10 × 50 − 5 = 495, with special tax of 10.00 and General Sales Tax of (495 + 10) × 10% = 50.500, so the line total is 555.500.

The guide allows rounding to 3 decimal places and up to 9, provided the difference is no more than 0.001. Make that difference your acceptance limit when you compare results.

Use the numbers only, not the XML files published in the guide. The guide’s examples are illustrative, and some of them contain defects, of which we name three. The unique identifiers on pp. 14 and 98 are not well formed, and the special tax examples contain doubled quotation marks. The return invoice examples also do not match their original invoices (pp. 24, 25, 47 and 74), so do not take them as expected results for testing a return.

Testing the unique identifier and resending

Your system generates the unique identifier, and the guide warns that failing to store an automatically generated identifier can lead to duplicate invoices when you resend. You can test this behavior entirely locally.

1. Confirm that your system stores the invoice number and its unique identifier before the first send attempt.
2. Simulate a connection failure inside your system, then confirm that the next attempt carries the same number and the same identifier.
3. Confirm that the identifier is well formed, and do not copy identifiers from the guide’s examples.

The details of this pair are in our article JoFotara UUID: Why It Comes Back With the ID.

Testing how you read the response

The guide describes the shape of the response on pp. 98 to 100, so you can build and test your handling of it before any submission. In summary, the structure is as follows.

• EINV_STATUS is the official status of the invoice. Its values are SUBMITTED, ALREADY_SUBMITTED and NOT_SUBMITTED.
• EINV_RESULTS holds an overall status (PASS or ERROR) and three groups, INFO, WARNINGS and ERRORS. Each item in them carries the type, the status, EINV_CODE, EINV_CATEGORY and EINV_MESSAGE.
• EINV_QR holds the QR code of an accepted invoice, and it comes back empty with a rejected invoice.

Test that your system does not judge an invoice by the technical HTTP status code alone, because the fourth instruction asks you to rely on EINV_STATUS. Test that it does not treat an invoice as accepted unless a QR code is present in the response. And test that it stores the error details internally and shows the user a simplified message, as the sixth instruction asks. Our article JoFotara Guidelines for Linked Systems: All Ten Explained covers these instructions together.

The first real submission with the least risk

This whole section is a Qoyod suggestion. It rests on the guide’s rules but does not quote it. The idea is to make the first invoice you send a simple real one, so that if an error appears you can find its source quickly.

1. Confirm the linking credentials before sending. Check that the Client ID and the Secret Key were created from device linking (ربط الأجهزة) on the income-source sequence you will issue invoices under. Our article JoFotara Client ID and Secret Key: Device Linking Steps shows how to create them.
2. Pick a simple real sale. Choose a new local invoice with one or two lines, of a type that matches the business’s registration at ISTD. Postpone types with extra conditions, such as development zone invoices, which require the buyer’s tax number.
3. Store the invoice identity before sending. Record the invoice number and its unique identifier before the request leaves your system.
4. Read the whole response. Look at EINV_STATUS and at whether a QR code is present, and do not stop at the status code.
5. Verify the code. The guide lets a taxpayer verify the QR code only by scanning it in the Sanad app, through the digital document verification option (التحقق من المستندات الرقمية). If the app shows the words “The document is valid” (الوثيقة صحيحة), it also shows the basic invoice data carried inside the code.
6. Widen gradually. Once the first invoice is accepted, add one new type at a time, such as a receivable invoice or a return invoice, when a transaction of that type actually occurs, until you cover the types your business issues.

At every step the same rule holds. An invoice that is accepted is an issued invoice, so do not send a sale that did not happen.

If the first invoice is rejected or the connection drops

Errors that local testing cannot reveal show up here, and each has a status code that points to it. Our article JoFotara Error Codes: Why an Invoice Is Rejected and How to Fix It covers rejections in detail. These are the main cases as the guide describes them.

• Status code 403. This points to a wrong Client ID or Secret Key. Check both values as you created them.
• Status code 500. The guide attributes it to an error in the tax number or the income-source sequence, and less often to the Client ID or the Secret Key. The tax rate in the file may also be outside the rates ISTD recognizes.
• Status code 400. This points to an error in the values of the XML file, which the message in EINV_MESSAGE details. It includes the message that the invoice type is not allowed for the business.
• Status code 504. This means your system did not reach the National Invoicing System, because of the taxpayer’s firewall or ISTD’s site.

In both the rejection case and the dropped connection, the guide asks for the same thing. After you correct the file, resend it with the same invoice number and the same unique identifier. When a request times out or the connection fails, retry without generating a new identifier. If the invoice had in fact been accepted and you did not receive the response, the status ALREADY_SUBMITTED comes back with the original QR code.

We also suggest logging every attempt at this stage, including the request, the response and the time of each (Qoyod suggestion). The tenth instruction asks for all operations to be logged, covering sending, response and resending, and that log is what you return to when you ask why a particular invoice was rejected.

When to contact ISTD

If the error persists after you have gone through the causes the guide lists, or if your question is about testing itself, the body the guide refers you to is the Invoicing Technical Support Committee at ISTD.

We suggest attaching to your question the invoice number and its unique identifier, the status code, and the text of EINV_MESSAGE exactly as it arrived (Qoyod suggestion). Do not send the Client ID or the Secret Key in the correspondence. The guide makes the taxpayer responsible for keeping them confidential, and says the taxpayer bears full responsibility for any unauthorized use.

How Qoyod handles invoice submission

If your business issues its invoices from Qoyod, building the file and sending it are not your job. Qoyod’s integration with the National Invoicing System works on this layer as follows, and you can read about it on the page for JoFotara integration.

• Building and sending the file. Qoyod builds the invoice file in UBL 2.1 format with its unique identifier (UUID) and sends it to the National Invoicing System without any manual intervention.
• An alert 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.

What remains yours is what belongs to the business itself, which is creating the Client ID and the Secret Key from device linking (ربط الأجهزة) and then using them inside your accounting software, as the joining guide asks. For a wider view of the system and how to connect your business to it, read our article Jordan’s National E-Invoicing System.

Frequently asked questions

Does JoFotara provide a test environment for developers?

Technical guide version 1.5 documents no test environment and no address for trial submissions. It gives a single address for submitting invoices. If you have a question about testing, the body the guide refers you to is the Invoicing Technical Support Committee at the Income and Sales Tax Department.

Should I send a trial invoice to confirm the link works?

We advise against it, as a Qoyod suggestion. An invoice the system accepts is an issued invoice that is not edited afterward, and it is corrected with a return invoice on quantities only. Make your first submission a simple real sale.

What can I test before the first submission?

You can test the structure of the XML file, the totals and taxes, the field rules, the storing and reuse of the unique identifier, and how you read the response. Whether the linking credentials are valid, whether the tax number and the income-source sequence match the business’s record, and whether the system can be reached only show up when you send.

How do I know the first invoice was accepted?

Read the status from the EINV_STATUS field and not from the status code alone, and confirm that a QR code is present in the EINV_QR field. A taxpayer who wants to verify the code can scan it in the Sanad app, through the digital document verification option.

Should I use the XML files published in the technical guide for testing?

Use the figures in the examples to compare calculation results, and do not copy the files themselves. Some of the guide’s examples contain defects, among them unique identifiers that are not well formed, doubled quotation marks, and return examples that do not match their original invoices.

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. 7 to 10, 19 to 21, 40 to 44, 69 to 71 and 97 to 107.
• ISTD’s National Invoicing System guides (in Arabic)