FAQ

How to start?

1. Register to the Tax Authority SandBox.
2. Create an App in the Sandbox.
3. USe this site to test your App.

Where are the Tax Authority Sandbox and Production?

Sandbox: https://openapi-portal.taxes.gov.il/sandbox
End points are at: https://openapi.taxes.gov.il/shaam/tsandbox
E.g: https://openapi.taxes.gov.il/shaam/tsandbox/longtimetoken/oauth2/authorize?response_type=code&client_id=b4fdcbc8307386180bd735305a2027ee&scope=scope

Production: https://openapi-portal.taxes.gov.il/shaam/production
End points are at: https://openapi.taxes.gov.il/shaam/production
E.g: https://openapi.taxes.gov.il/shaam/production/longtimetoken/oauth2/authorize?response_type=code&client_id=9c83a7320fecabd55319a63a82f34d7a&scope=scope

What is the flow to get an Allocation Number?

Get Authorization Code 🡆 Get Access Token 🡆 POST the invoice details and receive an Allocation Number.

The Access Token is valid for 10 minutes. So after 10 minutes:
Refresh Access Token 🡆 POST the invoice details and receive an Allocation Number.

The Refresh Token is valid for 1 month. So after 1 month:
Get new Authorization Code 🡆 Get a new Access Code 🡆 POST the invoice details and receive an Allocation Number.

When I try to get an Authorization Code I receive this error:
{"error":"unauthorized_client","error_description":"Invalid client ID or secret, or client not subscribed to this API"}

Either your client id, or secret are incorrect.
Or your redirect URI is incorrect. Note that it must match the URI you defined in the App (that you created in the Sandbox) and that it is CASE SENSITIVE.

When I try to get an Authorization Code I receive this error:
{"error":"invalid_request","error_description":"Redirect URI missing"}

Verify that you defined only ONE redirect URI for the app. Technically you can define more than
onr redirect uri. But if you do, you will get this error.

How can I identify the invoice or the client id that requested the Authorization Code?

In the GET request add a state parameter. It will be appended to the redirect call.
https://openapi.taxes.gov.il/shaam/tsandbox/longtimetoken/oauth2/authorize?response_type=code&client_id=6d2e5958492712a68a9a126377ca9ae1&scope=scope &state=123456%24%40!%26%5e%25%24
==>
https://localhost:44327/OpenAPI?code=847837487389478a66e &state=123456%24%40!%26%5e%25%24

When I try to get an Access Token I receive this error:
{"error":"invalid_request","error_description":"Missing authorization code"}

You did not send an Authorization Code.
For example, the body of the POST request is

When I try to get an Access Token I receive this error:
{"error":"invalid_request","error_description":"Redirect URI specified in the request is not configured in the client subscription"}

The App key and App secret are correct but the Redirect URI is incorrect.
Note that the Redirect URI is CASE SENSITIVE. Correct the URI here or in the App (in the "Sandbox") and try again.

When I try to get an Access Token I receive the following error:
{ "error": "invalid_grant", "error_description": "*[6d2e5958492712a68a9a126377ca9ae0] Failed to verify oauth request signature*" }

You sent an invalid Authorization Code.

When I try to get an Access Token I receive the following error:
{"error":"invalid_grant","error_description":"*[6d2e5958492712a68a9a126377ca9ae0] Authorization code was used before, message rejected*"}

The Authorization Code was used to get an Access Token. It can only be used once. Get a new Access Token and try again.

How does an Access Token response look like?

A valid token response looks as follows:

What is a Refresh Token?

The Access Token is valid for only 10 minutes.
After 10 minutes you can either get a new Access Token (possibly you will need to login into the Sandbox),
or you can get a new Access Token via the Refresh Token:

How does the Invoice JSON look like?

Here is a very simple example:

Here is a more elaborate example:

How can I validate the Invoice JSON?

You can validate your JSON using https://www.jsonschemavalidator.net/.
Here is the schema file. Download it and copy the schema to the validator.

When I try to get an Allocation Number I get the following error:
{ "httpCode": "401", "httpMessage": "Unauthorized", "moreInformation": "Cannot pass the security checks that are required by the target API or operation, Enable debug headers for more details." }

You sent an invalid token. The token is sent in the request headers:
Authorization: Bearer AAIgNmQyZTU5NTg0OTI3MTJhNjhhOWExMjYzNzdjYTlhZTDslQtGLXNTRZw77kL0yeXpUu4c3d7QzX1mt2_vTIEQbyBmeGNyAb1f635ZwC41GLq9XqaIwS7-XLJ7eINW0phDLMUIZ008MC5zGbnr_Oo2CQ

When I try to get an Allocation Number I receive this error:
{ "Status": 500, "Message": "Internal Server Error", "Error_Id": "71989079303" }

If you are testing against the Sandbox:
You may have used an invalid VAT number.
Note that as of today (20-AUG-2023) you can only use the following VAT numbers for the "VAT_Number" field in the Sandbox:
777777715, 777777723, 777777731, 777777749

If you get the error when working with the Production system there is no way for you to know :-(
Send an e-mail with the error to invoices@taxes.gov.il and hopefully someone there will help you.

When I try to get an Allocation Number I receive this error:
{"Status":406,"Message":"Not Acceptable","Error_Id":"83189028997"}

You are not allowed to get an Allocation Number for the "Vat_Number" you sent.
Either you sent the wrong "Vat_Number" or the owner of this "Vat_Number" did not grant you the authrization in איזור אישי.

How does an Allocation Number response look like?

A valid Allocation Number response looks like this:
{ "Status": 200, "Message": "Invoice approved", "Confirmation_Number": "20230820112155830232010517" }

How does an Invoice validation error look like?

You either get a 422 error code. For example, here is a validation error in the "Items"/"Category" field. You will need to find the error using a schema validator:

Can I get a token using Implicit Grant?

Implicit Grant means that you send the following request:
. https://openapi.taxes.gov.il/shaam/tsandbox/longtimetoken/oauth2/authorize?response_type=token&client_id=b4fdcbc8307386180bd735305a2027ee&scope=scope
bypassing the user login stage. You can not do that. You wll get the following error:
Response status 400 { "error": "unsupported_response_type", "error_description": "Implicit grant not supported" }

Where is the manual Invoice Number Allocation site?

https://www.gov.il/he/service/request-assignment-number-for-tax-invoice

How can I receive the Authorization Code in desktop applications?

You can either:
Implement a Web Server in your application. Listen on some port and receive the authorization rediect there.
That is, if you listen on port 8888 then the redirect URI will be "http://localhost:8888"

Or you can implement a Web site (on a Web server not on the desktop) specifically to receive the Authorization Code and then display it to the user.
When there is a need to receive an Allocation Number (and there is no valid Access Token) you will open a Web browser from your desktop application,
and display your site.
The user will click a link with your App details and the redirect will be into your site.
Then the user will copy the Authorization Code into your desktop application. From there you will need to implement the ability to POST
requests to the open-api Sandbox in order to receive the Access Token.

Note that you will need to implement the POST ability anyway to receive the Allocation Number.

See an example here: https://demo.open-api.co.il/desktop

I am testing my application. I receive an Authorization Code but when I try to get an Access Token I receive the following error: {"error":"invalid_request","error_description":"Redirect URI specified in the request is not configured in the client subscription"}

Are you using a redirect URI containing localhost?
It looks like you ca not user a redirect URI containing local host in the production portal.

The VAT number (מספר עוסק מורשה) of the vendor starts with 0. How to send it?

If you try to send "Vat_Number": 011111115 you will receive an error since numbers starting with 0 are considered to be Octal.
Send it as "Vat_Number": 11111115

Do my users need to register to the Tax Authority Personal Area (איזור אישי)?

Yes, your user need to register to the Tax Authority Personal Area (איזור אישי).
When they try to get an Allocation Number they will need to identify themselves to the Tax Authority system,
which is done via the Tax Authority Personal Area.

What are Permissions (הרשאות) in the Personal Area (איזור אישי)?

The הרשאות in איזור אישי are there to allow one user to allow another user to get Allocation Number in his heahlf.
A typical example is a business owner who wants to allow one or more of his employees to issue invoices in his behalf.

אני מנהל שכיר בעמותה. העמותה מפיקה חש/קבלה לפעילות המסחרית שלה. מה אני צריך לעשות?

מאחר שהעמותה מפיקה חש/קבלה לפעילות המסחרית שלה, ובהנחה שבחש/קבלה אתה גובה מע"מ אז החובה לקבלת מספר הקצאה חלה גם על העמותה.
עליך לפנות לאחד הדירקטורים של העמותה ולבקש ממנו להרשם לאיזור האישי.
לאחר מכן עליו להקים את העמותה דרך כפתור "רישום/עדכון פרטי תאגיד"
בשלב הבא עליו ניתן להיכנס למערכת ההרשאות דרך כפתור "הרשאה לפעולות דיגיטליות" שנמצא באיזור האישי שלו. עליו לתת לך הרשאה לקבל מספרי הקצאה.
רשות המיסים תשלח לך הודעה שהתקבלה בקשת הרשאה.
היכנס לאיזור האישי שלך, ואשר את הבקשה.
הדירקטור יקבל הודעה שהבקשה שלו אושרה.
מעתה תוכל אתה לקבל מספר הקצאה דרך ההזדהות שלך במערכת של רשות המיסים.