Sandbox UI guide
The sandbox mirrors the production user interface with test data and credentials. This guide shows how an integrator prepares a Partner account, requests only the required permissions, and how a customer organization authorizes that Partner before it can create invoices on the organization’s behalf.
Never use production secrets, certificates, SEAL PINs, or tax data in the sandbox. The screenshots below contain no usable password or API secret.
Partner account
The Partner dashboard provides access to the public profile, API credentials, authorized customer organizations, delegated invoices, job history, requests, and audit logs.
1. Complete the Partner profile
Open Partner → Partner profile. Enter the legal company name, legal form, and address. The tax identifier is managed by the platform and cannot be edited from this page.
In Catalog, add a clear business label and EN/FR/AR descriptions. Explain what your integration does, who it is for, and why the requested permissions are needed. This information helps an organization make an informed consent decision.
2. Select the requested permissions
Open the API tab and apply least privilege:
| Scope | Permitted operation |
|---|---|
invoice:read | Read invoices and their processing status |
invoice:write | Create or update invoices |
ttn:submit | Submit invoices to the Tunisian tax authority (TTN) |
digigo:sign | Initiate DigiGO signing, which still requires user approval |
seal:sign | Trigger SEAL signing when the organization has configured it |
These scopes are only the permissions proposed during activation. They grant no access until the organization explicitly approves them.
3. Handle Partner API credentials
Open Partner → API credentials to obtain the Partner OAuth2 client credentials. Keep the secret in a server-side secret manager. Never embed it in a browser or mobile application, commit it to source control, or send it to a customer organization.
The Clients page lists organizations that have granted effective access. A catalog listing or pending request alone is not an authorization.
Organization account
The Organization account manages invoices, TEIF imports, products, API applications, company and tax settings, and authorized Partners.
1. Verify the organization and integration method
Review the organization’s legal identity before producing invoices, especially the legal name and tax identifier returned by the Organization API.
For a direct integration without a Partner, open API Keys and create an OAuth2 application owned by the organization. The client secret is shown only during creation and must remain on the integrator’s server.
2. Find and authorize a Partner
Open App catalog, search for the Partner, and review its description, verification status, and proposed scopes.
Select Activate. The consent screen explains every requested permission. Cancel the operation if a scope is not justified and ask the Partner to reduce its default scopes.
Confirm the consent and enter the OTP received by the organization owner. The sandbox test code may be supplied by the Fatoora team; in production, use only the code delivered through the secure channel.
A successful activation displays Activated in the catalog and adds the organization to Partner → Clients. If confirmation fails, do not bypass consent. Record the time, Partner, organization, and error response, then contact support.
What happens after authorization
The Partner authenticates with its own OAuth2 credentials, selects an authorized organization as documented in the Partner API, reads the organization’s non-sensitive general identity, and creates, signs, or submits invoices only within the granted scopes.
To validate both integration models end to end, use the Bash workflow and the Postman collections linked from the Partner API reference and Organization API reference.
Validation checklist
- The Partner profile clearly describes the integration service.
- Only necessary scopes are requested.
- The organization reviews each permission before entering the OTP.
- The catalog displays Activated after confirmation.
- The organization appears in the Partner Clients list.
- The Partner can read general organization identity but not subscription, plan, or other sensitive organization data.
- A complete test invoice reaches the expected sandbox status.