Multi-tenant invoice API

Why one account per seller

In Saudi e-invoicing the seller is the legal issuer: its VAT number, invoice sequence and ZATCA link belong to it alone. A platform that invoices on behalf of many sellers therefore needs one WonderFatoora company per seller, not one shared account.

How it works today

• Each seller company has its own key. The key decides the seller, and nothing in the request can override it.
• Each company has its own gap-free numbering, customers, products and tax rates.
• Ids are scoped: a customer, product or tax-rate id from another company is treated as unknown.
• Each company's plan and limits apply to its own invoices.

Architecture checklist

1. Store one key per seller, encrypted, next to that seller's record.
2. Choose the key from the seller of the order, never from user input.
3. Verify the pairing once with GET /ping, which returns the company name.
4. Store WonderFatoora ids (invoices, customers) together with the seller they belong to.
5. Handle 401 per seller: that seller's key was revoked or has expired (token_expired), so ask them to reconnect.
6. Use external_reference values that are unique within each seller, such as your order id.