- Platform
- ZATCA e-invoicing (Fatoora)
- What it is
- The Zakat, Tax and Customs Authority’s e-invoicing system, rolled out in a generation phase and an integration phase in waves of taxpayers.
- What integration involves
- Generating compliant invoice documents, onboarding the invoicing solution, cryptographic identity for the device or solution, clearance or reporting of invoices through the published API, and archiving.
- Official source
- zatca.gov.sa
System integration
Planning enterprise integrations with Saudi digital platforms
ZATCA’s e-invoicing, Nafath identity, Etimad procurement and Wathq commercial-registration data are documented interfaces, and an integration with any of them is an engineering programme with a known shape. This guide sets out that shape — from sandbox onboarding to production responsibility — so the work can be scoped and procured precisely.
Planning guide Published 6 min read
01The short answer
What an integration with a national platform actually involves
Each platform publishes a specification, an onboarding process and a sandbox. The work is to read the specification as it is published, build against the sandbox with the authentication, logging, retry and error-handling behaviour the production interface will demand, and then cut over with the responsibilities for operating the connection written down. The technology is rarely the hard part; the sequencing, the identity model and who owns the interface after go-live are.
Interkey’s role in this is a software-engineering and system-integration team that scopes and builds against documented interfaces. This page describes the planning; it does not describe a delivery history, and the official sources linked below are the authority on each platform’s requirements.
02The platforms
Four platforms, and what integrating with each involves
Read the official documentation first; it changes, and this table is a map of the integration shape, not a substitute for the specification.
- Platform
- Nafath
- What it is
- The national digital identity and single sign-on service.
- What integration involves
- Delegating authentication of citizens and residents to the national identity provider, mapping the identity returned to your own user model, and handling consent and session lifecycle.
- Official source
- iam.gov.sa (Nafath)
- Platform
- Etimad
- What it is
- The government procurement and tendering platform.
- What integration involves
- Registering as a supplier, and where an entity integrates its own systems, aligning tender, bid and contract data with the platform’s published processes.
- Official source
- etimad.sa
- Platform
- Wathq
- What it is
- The Ministry of Commerce’s commercial-registration data services.
- What integration involves
- Consuming commercial-registration data through the published APIs, with the subscription, authentication and usage terms the service sets.
- Official source
- wathq.sa
03The sequence
From the published specification to a production connection
The order matters more than the speed. Each stage produces something the next one depends on, and skipping one is how an integration passes the sandbox and fails in production.
-
Read the specification as published
Versions, endpoints, document formats, error codes and rate limits, from the platform’s own developer material. Note what is mandatory and what is a recommendation.
-
Onboard to the sandbox
Register the solution or entity, obtain sandbox credentials, and build the integration against the sandbox exactly as it will run in production, including failure paths.
-
Settle authentication and identity
Certificates, tokens or delegated identity, their issuance and rotation, and how the identity the platform returns maps to your own users, roles and records.
-
Classify the data that crosses the interface
What leaves your systems, what comes back, its classification under your own policy, and where it is stored and for how long.
-
Build the operating behaviour in
Structured logging, observability, retries with idempotency keys, explicit error handling and an audit trail that a reviewer can follow end to end.
-
Cut over with responsibilities written down
Production credentials, the deployment path, who monitors the connection, who answers the platform’s change notices, and what happens when a version changes.
04The engineering decisions
Twelve decisions that decide whether the integration survives production
- Decision
- What to settle
- API onboarding
- Who registers with the platform, under which entity, and who holds the credentials issued.
- Sandbox versus production
- What differs between them — data, limits, certificates — and how a build proven in one is promoted to the other.
- Authentication
- The credential type the platform requires, its lifetime, its rotation, and where it is stored.
- Identity
- How an identity the platform asserts is mapped to your user model, and what happens when they disagree.
- Data classification
- The classification of every field that crosses the interface, and the handling rule each classification triggers.
- Logging
- What is logged, at which level, with which identifiers redacted, and for how long.
- Observability
- How the health, latency and error rate of the connection are seen, and by whom, on the observability platform you already run.
- API gateways
- Whether the connection runs through a managed gateway, and which policies — rate, authentication, transformation — live there.
- Retry and idempotency
- Which calls are safe to retry, the idempotency key that makes them safe, and the back-off the platform tolerates.
- Error handling
- The platform’s error codes mapped to explicit outcomes: retry, escalate, reject, or hold for human review.
- Auditability
- The record of what was sent, when, by which identity, with which response, kept where an auditor can read it.
- Deployment responsibility
- Who deploys, who operates, who is paged, and who owns the change when the platform publishes a new version.
05Designed to survive
Three failure modes every platform integration has to survive
Each of these happens to a working integration eventually. The engineering decisions above exist so that when it does, the outcome is a logged event and not an incident.
01
The platform publishes a new version
Endpoints, document formats or validation rules change on the platform’s schedule, not yours. The build tracks the specification version it targets, the sandbox re-run is rehearsed, and someone is named to read change notices.
02
A credential expires or is rotated
Certificates and tokens have lifetimes. Rotation is scheduled and tested before expiry, the secret lives in one place, and an authentication failure is an alert with an owner rather than a silent queue of rejected submissions.
03
A submission is sent twice
A timeout after the platform accepted the request is the classic case. Idempotency keys make the retry safe, the audit trail shows both attempts and one outcome, and the reconciliation report is the proof.
06Before you buy
Questions to resolve during procurement
Put these in the RFP. A supplier who answers them in specifics has read the specification; one who answers them in general has not.
- Which version of the platform specification is the build against, and who tracks changes to it
- Which entity registers with the platform, and who holds the issued credentials after handover
- How sandbox results are promoted to production, and what is re-tested at cutover
- What identity model is used, and how disagreements between the platform and your records are resolved
- The classification of every data field crossing the interface, and its retention
- What is logged, what is redacted, and where the audit trail lives
- Which calls are idempotent, and how duplicate submissions are prevented
- Who operates the connection after go-live, and who responds to a platform change notice
What Interkey brings, stated precisely
A software-engineering and system-integration team in Riyadh that scopes, builds, tests and operates integrations against documented interfaces, with the logging, observability and gateway practices linked above. Whether a given platform integration belongs in a programme, and under which entity’s registration, is settled in the first conversation against the platform’s own current requirements.
07Buyer questions
What buyers ask us
Direct answers to the questions that come up in real evaluations. Anything missing, ask us at the bottom of the page.
Do we need a separate integration for each platform?
Each platform has its own specification, credentials and onboarding, so each is its own integration. What should be shared is the engineering underneath: the gateway, the logging and audit approach, the retry and idempotency pattern and the identity mapping, so the second integration is cheaper than the first.
Where does the official specification live?
On each platform’s own site, linked in the table above. Build against the published version and treat this guide as the planning shape around it, not as the specification.
Can the integration be built and tested without touching production?
That is what the platform sandbox is for. The build is completed and its failure paths exercised against sandbox credentials, and production credentials are issued only at cutover, with what is re-tested at that point written down in advance.
Who is responsible for the connection after go-live?
Whoever the contract says, which is why it is one of the twelve decisions. Interkey can operate an integration under a written managed-services scope; the registration and credentials remain the entity’s.
From the insights library
Continue with integration
Practice
System integration in Saudi Arabia
Connecting the ERP, operational and legacy systems an organisation already runs, with an owner per interface.
PracticeAPI management and gateways
Interface inventory, policy, gateway implementation and operation, in-Kingdom where required.
SectorTechnology for government entities
In-Kingdom deployment end to end, Arabic-first software, and operation after handover.
Next step
Scope a platform integration
Name the platform, the systems on your side and who will operate the connection, and the reply comes from the engineers who would build it.
Or directly
+966-11-2180999 [email protected]Tawuniya Towers, North Tower, 7th Floor, King Fahad Highway, Olaya, P.O. Box 56835, Riyadh 11564, Saudi Arabia