Set up your organization

Stage 1 of 6. Do these tasks one time, before your app connects its first business.

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.
• Mode: Live or Sandbox. Live is real e-invoicing. Sandbox is for tests. Each mode has its own credentials and data.
• API key: the secret that your server sends with each API call. It identifies your organization.
• OAuth client: the client ID and client secret that your app uses to connect businesses.
• Webhook endpoint: a URL on your server. Wafeq ASP sends events to this URL when something changes.

Live and Sandbox

The Wafeq ASP portal has two modes: Live and Sandbox. Each mode has its own API keys, OAuth client, webhook endpoints, taxpayers and documents. Nothing goes from one mode to the other.

Start in Sandbox. Sandbox is free. Nothing in Sandbox goes to EmaraTax, the FTA or Peppol. When your integration works in Sandbox, do the same setup again in Live. Refer to Go live.

Set up your organization: the four steps

You do all four steps in the Wafeq ASP portal, in Sandbox mode.

Step 1: Sign in and select Sandbox

1. Go to the Wafeq ASP portal and sign in.
2. Select Sandbox.

Step 2: Create an API key

1. Go to Developer → API keys.
2. Create an API key. A Sandbox API key starts with pk_test_.
3. Store the key on your server. The portal shows the key one time only.

Your server sends the API key in the Authorization header of each API call. Refer to Authentication.

Step 3: Get your OAuth client and add your callback URLs

1. Go to Developer → Settings.
2. Copy the client ID and the client secret. Store the secret on your server. The portal shows the secret one time only.
3. Add your callback URLs (redirect URIs). You can add a maximum of 10 URLs. Each URL must use HTTPS. In Sandbox, http://localhost is also permitted.

Your app uses the OAuth client to connect businesses. Refer to Connect a taxpayer.

Step 4: Add a webhook endpoint

Many results come after your app submits a document. For example, the provider of the buyer sends a delivery receipt minutes later. The FTA sends its answer later again. Wafeq ASP sends each of these results to your webhook endpoint as an event. Without a webhook endpoint, your app must ask the API again and again.

1. Go to Developer → Webhooks.
2. Add the URL of your webhook endpoint. It must use HTTPS.
3. Select these events:
   • taxpayer.created, taxpayer.updated and taxpayer.deleted: a business gives, changes or loses a grant to your organization.
   • document.sent, document.status and document.reported: the delivery and the report to the FTA of the documents that your app submits.
   • document.received: a document that another business sends to one of your taxpayers.
4. Copy the signing secret, and store it on your server. Your server uses it to check that each event comes from Wafeq ASP.

Add the webhook endpoint before your app connects its first business. Then your app receives the taxpayer.created event of that first business. For the format of events and the signature check, refer to Webhooks.

After the setup

These items are not steps. Do them before businesses start to approve your app.

• The details that businesses see. When a business approves your app, it sees an approval page. This page shows the name, logo and support email of your organization. It also shows the website of your OAuth client. Make sure that these details are correct in the settings of your organization.
• The safety of your secrets. Keep the API key, the client secret and the signing secret on your server. Do not put them in browser code, mobile apps, URLs or logs.

Next

Stage 2: Connect a taxpayer.