Saudi Government System Integration: Developer Guide

Saudi Government System Integration

Saudi Arabia has a comprehensive ecosystem of digital government systems: National Access (Nafath), ZATCA, Muqeem, Absher, and hundreds of sector-specific systems. Companies needing to integrate with these systems face unified technical and security requirements.

Why Do Government Systems Reject Foreign Servers?

Saudi government agencies require digital service providers to meet:

1. data protection and localization — data does not leave the Kingdom
2. NCA compliance — National Cybersecurity Authority requirements
3. IP verification — confirming requests originate from a Saudi server
4. Audit trail — complete logs for every operation

Key Government Systems and Their Interfaces

1. ZATCA — Zakat, Tax and Customs Authority

# ZATCA Fatoora API (e-invoicing)
# Sandbox base URL
https://gw-fatoora.zatca.gov.sa/e-invoicing/developer-portal

# Production base URL
https://gw-fatoora.zatca.gov.sa/e-invoicing/core

// config/zatca.php
return [
 'base_url' => env('ZATCA_BASE_URL'),
 'certificate' => env('ZATCA_CERTIFICATE_PATH'),
 'private_key' => env('ZATCA_PRIVATE_KEY_PATH'),
 'vat_number' => env('ZATCA_VAT_NUMBER'),
 'cr_number' => env('ZATCA_CR_NUMBER'),
];

class ZatcaInvoiceService
{
 public function reportInvoice(Invoice $invoice): array
 {
 $invoiceXml = $this->buildXml($invoice);
 $signedXml = $this->signXml($invoiceXml);
 $hash = hash('sha256', base64_encode($signedXml));

 $response = Http::withHeaders([
 'accept' => 'application/json',
 'accept-language' => 'en',
 'accept-version' => 'V2',
 'Authorization' => 'Basic ' . base64_encode(
 config('zatca.certificate') . ':' . config('zatca.private_key')
 ),
 ])->post(config('zatca.base_url') . '/invoices/reporting/single', [
 'invoiceHash' => $hash,
 'uuid' => $invoice->uuid,
 'invoice' => base64_encode($signedXml),
 ]);

 return $response->json;
 }
}

2. Absher / Absher for Business

// OAuth flow with Absher
Route::get('/absher/callback', function (Request $request) {
 $code = $request->input('code');

 $token = Http::post('https://absher.sa/oauth/token', [
 'grant_type' => 'authorization_code',
 'client_id' => config('absher.client_id'),
 'client_secret' => config('absher.client_secret'),
 'code' => $code,
 'redirect_uri' => route('absher.callback'),
 ])->json;

 session(['absher_token' => $token['access_token']]);
 return redirect('/dashboard');
});

Security Requirements for Government Integration

Security Certificates

# TLS 1.2+ mandatory
# SSL certificate from internationally recognized CA
# Certificate validity at least 12 months

# Verify SSL for any government API
openssl s_client -connect gw-fatoora.zatca.gov.sa:443 -tls1_2

API Firewall

location /api/government {
 limit_req zone=govt_api burst=20 nodelay;
 limit_req_status 429;

 add_header X-Content-Type-Options nosniff;
 add_header X-Frame-Options DENY;
}

Encrypting Sensitive Data

class EncryptedNationalId extends Cast
{
 public function get($model, string $key, $value, array $attributes): string
 {
 return decrypt($value);
 }

 public function set($model, string $key, $value, array $attributes): string
 {
 return encrypt($value);
 }
}

Recommended Application Architecture

app/
├── Services/
│ ├── Government/
│ │ ├── NafathService.php
│ │ ├── ZatcaService.php
│ │ ├── AbsherService.php
│ │ └── MhrsdService.php
│ └── GovBaseService.php // shared: logging, retry, error handling
├── Jobs/
│ ├── ReportInvoiceToZatca.php
│ └── VerifyWorkerStatus.php
└── Models/
 └── GovAuditLog.php // log all government API calls

abstract class GovBaseService
{
 protected function request(string $method, string $url, array $data = []): array
 {
 $start = microtime(true);

 $response = Http::retry(3, 1000)
 ->timeout(30)
 ->withHeaders($this->getHeaders)
 ->$method($url, $data);

 GovAuditLog::create([
 'service' => static::class,
 'url' => $url,
 'status_code' => $response->status,
 'duration_ms' => round((microtime(true) - $start) * 1000),
 'timestamp' => now,
 ]);

 if ($response->failed) {
 throw new GovApiException($response->body, $response->status);
 }

 return $response->json;
 }
}

cloud.net.sa Servers for Government Integration

cloud.net.sa provides the right infrastructure for integrating with Saudi government systems:

• Location: Riyadh and Jeddah — very low latency to government systems
• Dedicated IP: available at 400 SAR/year — required for IP whitelisting
• uptime عالي مع ضمان تعاقدي: by contract — government systems require high continuity
• Daily backup: all plans — business continuity

The Business plan (4 vCPU, 8GB) is most appropriate for most government integration applications.

Summary

Integration with Saudi government systems requires serious technical compliance. Investing in a reliable Saudi server with a dedicated IP and a documented SLA is the foundation of any successful integration with the digital government ecosystem.

---

Get Started

Ready to build your project? Configure your cloud server with the specs your app needs, or view plans and pricing.