Sandbox

Use this page to test your integration in Sandbox before you go live. It gives the full list of the differences between Sandbox and Live.

This page uses these terms:

• Wafeq ASP portal: the website where you manage your organization, at portal-einvoicing.wafeq.com.
• Your organization: the account of your company in the Wafeq ASP portal. Your company builds the app that uses the Wafeq ASP API.
• Your app: the software that your company builds.
• Live and Sandbox: the two modes of Wafeq ASP. Live is real e-invoicing. Sandbox is for tests.
• Grant: the permission that a business gives to your organization. A grant lets your app submit e-invoices in which that business is the seller.
• Taxpayer: a business from which your organization has an active grant. The API uses the Taxpayer ID (txpay_…) to identify it.
• Test taxpayer: a taxpayer that Wafeq ASP makes in Sandbox. No real business is behind it.
• Buyer: the business that receives the document.
• FTA: the UAE Federal Tax Authority. In Live, Wafeq ASP reports each e-invoice to the FTA.
• EmaraTax: the online portal of the FTA. In Live, a business appoints Wafeq ASP in EmaraTax.
• Peppol: the network that UAE businesses use to exchange e-invoices.
• TIN: the 10-digit number that the FTA gives a business. A UAE Peppol ID is 0235: followed by the TIN.
• VAT TRN: the VAT registration number of a business: 15 digits, ending in 03.
• FTA placeholder address: an address that Wafeq ASP uses instead of the Peppol ID of the buyer. Wafeq ASP uses it when it reports a document to the FTA only.
• Export and deemed supply: two special scenarios that your app sets in transaction_type_code. Refer to Special scenarios.

What Sandbox is

• Sandbox is free. Your organization needs no subscription and no taxpayer seats in Sandbox. Your organization can connect a maximum of 100,000 test taxpayers.
• Sandbox is separate from Live. Sandbox has its own API keys, OAuth client, webhook endpoints, taxpayers, grants and documents. Nothing goes from Sandbox to Live.
• Nothing in Sandbox goes to EmaraTax, the FTA or Peppol. The sections below tell you what Wafeq ASP does instead.

When your integration works in Sandbox, move it to Live. Refer to Go live.

Before you start

In the Wafeq ASP portal, select Sandbox. Then do the setup of your organization in Sandbox. Refer to Set up your organization (stage 1).

• Create a Sandbox API key. It starts with pk_test_.
• Get the Sandbox OAuth client, and add your callback URLs. In Sandbox, http://localhost is also permitted.
• Add a webhook endpoint for Sandbox.

Connect a test taxpayer: the four steps

In Live, a business onboards in EmaraTax and then approves your app. In Sandbox, you act as the business. Wafeq ASP simulates the onboarding and makes a test taxpayer. Your app uses the same connection flow as in Live. Refer to Connect a taxpayer (stage 2).

Step 1: Redirect to the Sandbox authorization page

Start the connection flow of your app with your Sandbox OAuth client. Use the Sandbox authorization page:

https://portal-einvoicing.wafeq.com/sandbox/oauth/authorize

The parameters are the same as in Live.

To select the TIN of the test taxpayer, send it in tin_hint. The TIN has 10 digits and starts with 1. If you do not send tin_hint, Wafeq ASP selects a random TIN that is not in use.

Step 2: Simulate the onboarding

On the page of Wafeq ASP, select Simulate EmaraTax onboarding. Wafeq ASP makes a test taxpayer with these details:

• TIN: your tin_hint, or a random TIN that is not in use.
• VAT TRN: the TIN, followed by 00003.
• Sign-in email: your email address. The test taxpayer signs in to its workspace with this address.

Follow the pages of the simulation. They ask for the address of the test taxpayer, with the emirate.

Wafeq ASP refuses a tin_hint in these cases:

• The TIN is already in use in Sandbox. If you onboarded a test taxpayer with this TIN, sign in as that taxpayer instead.
• Wafeq ASP reserves the TIN for tests. This includes the TINs of the test buyers on this page.

Step 3: Approve your app

Wafeq ASP shows the approval page, as in Live. Approve your app. Wafeq ASP creates the grant and redirects to your callback URL with the code.

Step 4: Exchange the code

Exchange the code at the Sandbox token endpoint:

https://portal-einvoicing.wafeq.com/sandbox/oauth/token

The response gives the Taxpayer ID and the grant ID of the test taxpayer. Store them. You can also get them later with GET /grants and your Sandbox API key.

After the connection

These sections are not steps. They tell you how to call the API in Sandbox, and what Sandbox simulates.

Call the API in Sandbox

Call the API with your Sandbox API key and the IDs of the test taxpayer:

curl https://api.wafeq.com/ae/v1/invoices \
  -H "Authorization: Api-Key $SANDBOX_API_KEY" \
  -H "x-ae-taxpayer-id: $TAXPAYER_ID" \
  -H "x-ae-grant-id: $GRANT_ID"

• Live and Sandbox use the same base URL. The pk_test_ key sends the call to Sandbox.
• Do not add /sandbox to API paths. Only the pages of the Wafeq ASP portal use /sandbox.
• In Sandbox, authenticate with the Sandbox API key. Refer to Authentication.

Submissions and delivery

• Wafeq ASP makes the e-invoice and runs the same checks as in Live.
• Wafeq ASP does not look for the buyer on Peppol, and it sends nothing on Peppol. Thus a buyer that you invent works. Wafeq ASP simulates the delivery to this buyer.
• The document.status events contain simulated: true.
• Wafeq ASP also simulates queued delivery (Prefer: respond-async).

A copy for the buyer. If the buyer is an active taxpayer in Sandbox, the buyer receives a copy of the document. Use this to test both sides of an exchange:

1. Connect two test taxpayers.
2. Submit a document from one test taxpayer to the other. Use 0235: followed by the TIN of the second test taxpayer as customer.id.
3. Read the copy as the second test taxpayer. Your grant from this taxpayer needs the scopes invoices:read and inbound:read. Your organization also receives a document.received event.

The delivery_status of the submitted document is then delivered_confirmed. When the buyer is not an active taxpayer in Sandbox, the delivery_status is sent.

The report to the FTA

Wafeq ASP does not report documents to the FTA in Sandbox. tdd_status stays not_reported, and no real document.reported event comes.

To test how your app processes a document.reported event, send a test event:

1. In the Wafeq ASP portal, go to Developer → Webhooks.
2. Select a webhook endpoint that has the document.reported event.
3. Send a test event, and select the outcome of the report.

A test event contains test: true. It changes no document.

Test buyers

In Sandbox, Wafeq ASP treats a buyer that you invent as a buyer on Peppol. Two reserved test buyers let you test the other routes. Send one of them in customer.id.

0235:1999201000: a buyer that is not on Peppol.

• Result: Wafeq ASP does not deliver the document. It simulates a report to the FTA only.
• Placeholder address: for an export, Wafeq ASP uses the FTA placeholder address 0235:9900000099. For any other document, it uses 0235:9900000098. The buyer can be in the UAE or outside the UAE.
• Response: 202 with status: reporting_only, as in Live. The submission needs an Idempotency-Key.

0235:1999202000: Peppol is not available at this time.

• Check: POST /invoices/validate gives the warning smp_unavailable.
• Submission: Wafeq ASP refuses it with 503 smp_unavailable. Wafeq ASP accepts nothing.
• Use: test how your app retries a submission with the same Idempotency-Key.

Other routes. These routes work as in Live, but Wafeq ASP only simulates the report to the FTA:

• A document without customer.id goes to an FTA placeholder address. Refer to Submit a document (stage 3).
• A deemed supply always goes to 0235:9900000097, whatever the buyer.

Simulate a deregistration

To test what happens when a business deregisters, simulate the deregistration in the workspace of the test taxpayer:

1. Sign in to the workspace of the test taxpayer with the email address of step 2.
2. Simulate the deregistration there.

After the deregistration, your app cannot submit documents with this taxpayer as the seller. Your app can still read the documents of the taxpayer.