التكامل مع الأنظمة الحكومية السعودية: دليل المطور

التكامل مع الأنظمة الحكومية السعودية

المملكة العربية السعودية تمتلك منظومة متكاملة من الأنظمة الحكومية الرقمية: النفاذ الوطني، زاتكا (ZATCA)، موارد، أبشر، النفاذ، ومئات الأنظمة القطاعية. الشركات التي تحتاج التكامل مع هذه الأنظمة تواجه متطلبات تقنية وأمنية موحدة.

لماذا يرفض النظام الحكومي سيرفرك الأجنبي؟

الأجهزة الحكومية السعودية تُلزم مزودي الخدمة الرقمية باستيفاء:

1. حماية وتوطين البيانات — البيانات لا تغادر المملكة
2. الامتثال لـ NCA — اشتراطات الهيئة الوطنية للأمن السيبراني
3. IP verification — التأكد من أن الطلبات مصدرها سيرفر سعودي
4. Audit trail — سجلات كاملة لكل عملية

أبرز الأنظمة الحكومية وواجهاتها

1. ZATCA — هيئة الزكاة والضريبة

# ZATCA Fatoora API (الفواتير الإلكترونية)
# Base URL بيئة الاختبار
https://gw-fatoora.zatca.gov.sa/e-invoicing/developer-portal

# Base URL الإنتاج
https://gw-fatoora.zatca.gov.sa/e-invoicing/core

// إعداد ZATCA في Laravel
// config/zatca.php
return [
 'base_url' => env('ZATCA_BASE_URL'),
 'certificate' => env('ZATCA_CERTIFICATE_PATH'),
 'private_key' => env('ZATCA_PRIVATE_KEY_PATH'),
 'pih' => env('ZATCA_PIH'), // Previous Invoice Hash
 'vat_number' => env('ZATCA_VAT_NUMBER'),
 'cr_number' => env('ZATCA_CR_NUMBER'),
];

// توليد الفاتورة الإلكترونية
class ZatcaInvoiceService
{
 public function generateInvoice(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. أبشر / أبشر أعمال

# التكامل مع خدمات أبشر للأعمال
# يتطلب: تسجيل في بوابة أبشر + سيرفر سعودي + SSL

# أنواع التكامل المتاحة:
# - OAuth 2.0 للتحقق من هوية المستخدم
# - API لخدمات العمالة والتأشيرات

// OAuth flow مع أبشر
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;

 // حفظ token وبدء الجلسة
 session(['absher_token' => $token['access_token']]);
 return redirect('/dashboard');
});

3. موارد (Ministry of Human Resources)

// التحقق من هوية العامل
$response = Http::withToken($accessToken)
 ->get('https://api.mhrsd.gov.sa/v1/worker/verify', [
 'iqama_number' => $request->iqama_number,
 'sponsor_id' => config('mhrsd.sponsor_id'),
 ]);

متطلبات الأمان للتكامل الحكومي

شهادات الأمان

# TLS 1.2+ إلزامي
# شهادة SSL من CA معترف بها دولياً
# مدة صلاحية الشهادة لا تقل عن 12 شهراً
# wildcard certificates مقبولة

# التحقق من صحة SSL لأي API حكومي
openssl s_client -connect gw-fatoora.zatca.gov.sa:443 -tls1_2

جدار الحماية للـ API

# السماح فقط للـ API الحكومي بالوصول الخارجي
# وتقييد الوصول الداخلي
location /api/government {
 # Rate limiting صارم
 limit_req zone=govt_api burst=20 nodelay;
 limit_req_status 429;

 # headers الأمان
 add_header X-Content-Type-Options nosniff;
 add_header X-Frame-Options DENY;
}

# ufw: السماح فقط للـ IPs الحكومية المعروفة
# (تحقق من قائمة IPs المعتمدة من كل جهة)
ufw allow from 185.X.X.X to any port 443 comment "ZATCA API"

تشفير البيانات الحساسة

// تشفير الأرقام الوطنية ورقم الهوية
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);
 }
}

// في Model
protected $casts = [
 'national_id' => EncryptedNationalId::class,
];

نموذج بنية التطبيق

// بنية موصى بها للتكامل مع أنظمة متعددة
app/
├── Services/
│ ├── Government/
│ │ ├── NafathService.php
│ │ ├── ZatcaService.php
│ │ ├── AbsherService.php
│ │ └── MhrsdService.php
│ └── GovBaseService.php // مشترك: logging, retry, error handling
├── Jobs/
│ ├── ReportInvoiceToZatca.php
│ └── VerifyWorkerStatus.php
└── Models/
 └── GovAuditLog.php // سجل جميع الاتصالات الحكومية

// GovBaseService.php - Base class مشتركة
abstract class GovBaseService
{
 protected function request(string $method, string $url, array $data = []): array
 {
 $start = microtime(true);

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

 $this->logRequest($url, $data, $response, microtime(true) - $start);

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

 return $response->json;

 } catch (Exception $e) {
 $this->logError($url, $e);
 throw $e;
 }
 }

 private function logRequest(string $url, array $data, $response, float $duration): void
 {
 GovAuditLog::create([
 'service' => static::class,
 'url' => $url,
 'status_code' => $response->status,
 'duration_ms' => round($duration * 1000),
 'timestamp' => now,
 'success' => $response->successful,
 ]);
 }
}

سيرفرات كلاود للتكامل الحكومي

كلاود (cloud.net.sa) يوفر البنية التحتية المناسبة للتكامل مع الأنظمة الحكومية السعودية:

• موقع: الرياض وجدة — زمن استجابة منخفض جداً للأنظمة الحكومية
• IP مخصص: متاح بـ 400 ريال/سنة — ضروري لـ IP whitelisting
• Uptime 99.99%: بالعقد — الأنظمة الحكومية تتطلب استمرارية عالية
• Backup يومي: جميع الخطط — استمرارية الأعمال

باقة أعمال (4 vCPU، 8GB) هي الأنسب لمعظم تطبيقات التكامل الحكومي.

خلاصة

التكامل مع الأنظمة الحكومية السعودية يتطلب جدية في الامتثال التقني. الاستثمار في سيرفر سعودي موثوق مع IP مخصص وSLA موثق هو أساس أي تكامل ناجح مع المنظومة الحكومية الرقمية.

---

ابدأ الآن

جاهز تبني مشروعك؟ اختر خادمك السحابي بالمواصفات اللي يحتاجها تطبيقك، أو راجع الباقات والأسعار.