Multi-tenant SaaS integration

One key, one company

Every WonderFatoora company is a separate account with its own VAT number, invoice sequence and ZATCA link. A key belongs to exactly one company, and the seller on every invoice is the key's company. No request field can choose another company; a company or seller identifier sent in the body is ignored.

Case A: your SaaS bills its own customers

You are the seller. Your company has a WonderFatoora account and an API key; each of your customers is a buyer on your invoices.

1. Create a key for your company with invoices:write, invoices:issue and invoices:read.
2. When a payment succeeds, create the invoice with external_reference set to your payment or billing-period id.
3. Store the returned customer.id with your customer record and reuse it next time.
4. Read the invoice until zatca.deliverable is true, then send public_url with your receipt.

The SaaS billing API page walks through this in full. A server app you registered in My apps can do the same with OAuth client credentials: its token acts for your own company only.

Case B: your customers invoice their buyers through your product

Each of your customers is a seller and needs their own WonderFatoora company, on a plan that includes app connections (the plans with API access). Each customer connects their company to your app once, through OAuth:

1. Register your app in Settings → Developers → My apps, with your exact redirect URI and the scopes your product needs.
2. Your customer clicks "Connect WonderFatoora" in your product. Send them to /oauth/authorize with PKCE and a state.
3. They sign in, choose their company and approve. You receive a code at your redirect URI; exchange it at /oauth/token for an access token and a refresh token, and store the refresh token encrypted against that customer.
4. The token response names the company (company_id), and every API answer repeats it in meta.company_id. Your token for one customer can never reach another customer's data.
5. Your customer can disconnect your app at any time from their dashboard; their tokens stop at once. Handle 401 invalid_token by asking them to connect again.

Usage counts against each customer company's own plan, and every call shows in their request log under your app's name.

Without OAuth, the same works with one key per customer company:

1. Your customer creates a key in their WonderFatoora account, with only the scopes your product needs, and enters it in your product.
2. Store each key encrypted, linked to that customer's account. Never share a key between companies.
3. Call the API with the key of the company the invoice belongs to. Confirm the pairing once with GET /ping, which returns the company name.
4. Your customer can revoke the key in their account at any time. Handle 401 by asking them to reconnect.

Isolation

• A key reads and writes only its own company's data. An invoice or customer id from another company is answered exactly like an id that does not exist.
• Product and tax-rate ids are checked against the key's company.
• Every call is logged against the key that made it.