System integration
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
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
Read the official documentation first; it changes, and this table is a map of the integration shape, not a substitute for the specification.
| Platform | What it is | What integration involves | Official source |
|---|---|---|---|
| ZATCA e-invoicing (Fatoora) | The Zakat, Tax and Customs Authority’s e-invoicing system, rolled out in a generation phase and an integration phase in waves of taxpayers. | 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. | zatca.gov.sa |
| Nafath | The national digital identity and single sign-on service. | 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. | nafath.sa |
| Etimad | The government procurement and tendering platform. | Registering as a supplier, and where an entity integrates its own systems, aligning tender, bid and contract data with the platform’s published processes. | etimad.sa |
| Wathq | The Ministry of Commerce’s commercial-registration data services. | Consuming commercial-registration data through the published APIs, with the subscription, authentication and usage terms the service sets. | wathq.sa |
03The sequence
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.
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.
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.
Certificates, tokens or delegated identity, their issuance and rotation, and how the identity the platform returns maps to your own users, roles and records.
What leaves your systems, what comes back, its classification under your own policy, and where it is stored and for how long.
Structured logging, observability, retries with idempotency keys, explicit error handling and an audit trail that a reviewer can follow end to end.
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
| 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
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.
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.
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.
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
Put these in the RFP. A supplier who answers them in specifics has read the specification; one who answers them in general has not.
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
Direct answers to the questions that come up in real evaluations. Anything missing, ask us at the bottom of the page.
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.
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.
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.
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
Connecting the ERP, operational and legacy systems an organisation already runs, with an owner per interface.
PracticeInterface inventory, policy, gateway implementation and operation, in-Kingdom where required.
SectorIn-Kingdom deployment end to end, Arabic-first software, and operation after handover.
Next step
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 info@interkey.com.saTawuniya Towers, North Tower, 7th Floor, King Fahad Highway, Olaya, P.O. Box 56835, Riyadh 11564, Saudi Arabia