أمثلة تكامل بمنصّة NET.

هذا الدليل موجّه للمطوّرين وفِرَق التكامل التقني الذين يربطون أنظمة ‎.NET‎ (لغة C#) بمنصة فاتورة ضمن الفاتورة الإلكترونية في السعودية. موضوعه الوحيد: كيف تبني تكاملًا كاملًا من طرف إلى طرف بلغة C# يصادق على واجهات منصة فاتورة (Fatoora API)، ويحسب تجزئة الفاتورة، ويرمّز الـ XML بصيغة Base64، ويرسل الفاتورة إلى نقطتي المسح (Clearance) والإبلاغ (Reporting)، ويعالج الاستجابة والأخطاء بأمان.

نفترض أنك قرأت بالفعل دليل المصادقة في واجهة الفوترة، وتعرف من أين تأتي شهادة الختم التشفيري (CSID) وسرّها. كما نفترض اطّلاعك على نقاط نهاية API لمنصة فاتورة وإرسال الفاتورة عبر API. هذا الدليل يبدأ من حيث تنتهي تلك الأدلة: من الكود الفعلي القابل للنسخ والتشغيل في مشروع ‎.NET‎.

الأمثلة هنا مكتوبة بلغة C# الحديثة باستخدام HttpClient من مكتبة System.Net.Http، وSHA256 من System.Security.Cryptography، وSystem.Text.Json لتحليل الاستجابة. هذه أمثلة تعليمية تشرح الطبقة التقنية للتكامل المباشر مع منصة فاتورة، وهي مستقلة عن منتج قيود. إن كنت تبحث عن حل جاهز بدون كتابة كود، فإن قيود يربط منشأتك بمنصة فاتورة تلقائيًا دون الحاجة لبناء هذا التكامل بنفسك.

لماذا ‎.NET‎ خيار عملي للتكامل مع منصة فاتورة

كثير من أنظمة تخطيط الموارد (ERP) وأنظمة نقاط البيع في السوق السعودي مبنية على منصة ‎.NET‎. لذلك يصبح ربط هذه الأنظمة بمنصة فاتورة مباشرة من داخل C# خيارًا طبيعيًا لفِرَق كثيرة. تمنحك مكتبة System.Security.Cryptography كل ما تحتاجه لحساب تجزئة SHA-256 وتوقيع المستندات، بينما يتولى HttpClient طبقة النقل بكفاءة وأمان.

نقطة محورية نضعها أمامك من البداية: واجهات الفوترة في منصة فاتورة لا تستخدم OAuth. لا توجد نقطة نهاية لطلب رمز وصول (Access Token). المصادقة تعتمد على شهادة CSID مباشرة في كل طلب عبر ترويسة Basic. أبقِ هذه الحقيقة في ذهنك طوال هذا الدليل، فهي تحدد كيف تبني عميل HTTP في C#.

سنبني التكامل على مراحل واضحة. أولًا نجهّز ترويسة المصادقة الأساسية. ثم نحسب تجزئة الفاتورة. بعدها نرمّز الـ XML بصيغة Base64. ثم نرسل الطلب ونقرأ الاستجابة. وأخيرًا نضيف طبقة معالجة الأخطاء وإعادة المحاولة. كل مرحلة تأتي بكود C# كامل قابل للنسخ.

قبل أن نبدأ، يفيد أن ترسم في ذهنك خريطة الطبقات التي يمرّ بها أي طلب. الطبقة الأولى طبقة بناء المستند، إذ تنتج فاتورة بصيغة UBL XML متوافقة مع مخطط الهيئة. الطبقة الثانية طبقة التشفير، وفيها تحسب التجزئة وتوقّع المستند. الطبقة الثالثة طبقة النقل، وفيها تبني طلب HTTP موثّق وترسله. الطبقة الرابعة طبقة الاستجابة، وفيها تقرأ النتيجة وتعالج الأخطاء. هذا الفصل بين الطبقات ليس ترفًا تنظيميًا، بل هو ما يجعل تكاملك قابلًا للاختبار والصيانة على المدى الطويل.

في مشاريع ‎.NET‎ الجادة، يُترجَم هذا الفصل إلى أصناف مستقلة. صنف للمصادقة، وصنف للتجزئة، وصنف للترميز، وصنف لعميل HTTP، وصنف لتحليل الاستجابة. الأمثلة في هذا الدليل تتبع هذا التقسيم بدقة، حتى تنقلها كما هي إلى مشروعك دون إعادة هيكلة. كل صنف يحمل مسؤولية واحدة واضحة، وهو ما يسهّل كتابة اختبارات الوحدة لكل جزء على حدة.

المرحلة الأولى: بناء ترويسة المصادقة الأساسية

المصادقة على منصة فاتورة مصادقة أساسية (Basic Authentication). تأخذ معرّف الشهادة (CSID) وسرّه المرافق، تدمجهما بالشكل CSID:secret، ثم ترمّز الناتج بصيغة Base64 وتضعه في ترويسة Authorization. لاحظ أن الاسم الصحيح هو CSID وليس CCSI، وهذا خطأ إملائي شائع يربك المطوّرين.

في C# نستخدم Convert.ToBase64String على بايتات النص بترميز UTF-8. الكود التالي يبني الترويسة:

توليد ترويسة Basic بلغة C#

using System;
using System.Text;

public static class FatooraAuth
{
    // يبني قيمة ترويسة Authorization من معرّف الشهادة والسرّ
    public static string BuildBasicHeader(string csid, string secret)
    {
        // الصيغة المطلوبة: CSID:secret ثم ترميز Base64
        string raw = $"{csid}:{secret}";
        byte[] bytes = Encoding.UTF8.GetBytes(raw);
        string encoded = Convert.ToBase64String(bytes);
        return $"Basic {encoded}";
    }
}

// مثال على الاستخدام
string csid = Environment.GetEnvironmentVariable("FATOORA_CSID");
string secret = Environment.GetEnvironmentVariable("FATOORA_SECRET");
string authHeader = FatooraAuth.BuildBasicHeader(csid, secret);
Console.WriteLine(authHeader); // Basic c29tZS1jc2lkOnNlY3JldA==

لاحظ أننا قرأنا CSID والسرّ من متغيرات البيئة لا من نص مكتوب داخل الكود. هذه بيانات حساسة. لا تضعها في الكود ولا في مستودع git ولا في ملفات الإعداد المرفوعة. اقرأها من متغيرات البيئة أو من خزنة أسرار مثل Azure Key Vault. أمان هذه البيانات مسؤوليتك أنت، لأن من يحصل عليها يستطيع انتحال هوية جهازك أمام الهيئة.

تستحق صيغة الترميز توضيحًا إضافيًا. الترميز بصيغة Base64 ليس تشفيرًا، بل تحويل قابل للعكس. أي شخص يحصل على قيمة الترويسة يستطيع فكّها بسهولة واستخراج CSID والسرّ. لذلك تبقى الحماية الحقيقية في طبقة النقل المشفّرة (TLS) وفي حفظ بيانات الاعتماد بعيدًا عن أعين المتطفّلين. لا تفترض أن Base64 يخفي شيئًا، فهو مجرد صيغة نقل آمنة ضمن نص HTTP.

من ناحية دورة حياة الشهادة، تبدأ رحلتك بشهادة امتثال (Compliance CSID) تستخدمها في بيئة الاختبار للتأكد من أن فواتيرك تجتاز فحوص الهيئة. بعد نجاح فحص الامتثال، تحصل على شهادة الإنتاج (Production CSID) التي تستخدمها في البيئة الحية. هاتان شهادتان مختلفتان بسرّين مختلفين، ويجب أن يفصل تطبيقك بينهما عبر إعدادات البيئة. خطأ شائع أن يستخدم المطوّر شهادة الاختبار في الإنتاج أو العكس، فتُرفض كل الطلبات برمز 401 دون سبب واضح. اجعل اختيار الشهادة مرتبطًا ببيئة التشغيل لا مكتوبًا يدويًا.

في تطبيق ‎.NET‎ عملي، تخزّن قيمتي CSID والسرّ لكل بيئة في خزنة الأسرار، ثم تحقنهما عبر نظام الإعداد (Configuration) إلى الصنف المسؤول عن المصادقة. بهذا لا يلامس كودك القيم الفعلية أبدًا، وتستطيع تدوير الأسرار (Secret Rotation) دون إعادة نشر التطبيق. هذه ممارسة أمنية أساسية تفصل بين الكود والبيانات الحساسة.

المرحلة الثانية: حساب تجزئة الفاتورة (Invoice Hash) بخوارزمية SHA-256

قبل إرسال أي فاتورة، تحتاج إلى حساب تجزئتها التشفيرية. تستخدم منصة فاتورة خوارزمية SHA-256 لحساب تجزئة مستند الفاتورة بصيغة UBL XML. هذه التجزئة تُستخدم لاحقًا في التوقيع وفي بناء جسم الطلب، وتثبت أن الفاتورة لم تُعدَّل بعد توقيعها.

في C# نستخدم صنف SHA256 من System.Security.Cryptography. الناتج بايتات خام، نرمّزها عادة بصيغة Base64 لإرسالها في جسم JSON. الكود التالي يحسب التجزئة من نص الـ XML:

حساب SHA-256 وترميزه Base64 بلغة C#

using System;
using System.Text;
using System.Security.Cryptography;

public static class InvoiceHasher
{
    // يحسب تجزئة SHA-256 لمستند الفاتورة ويعيدها مرمّزة Base64
    public static string ComputeInvoiceHash(string ublXml)
    {
        // مهم: استخدم البايتات الخام للمستند كما هي قبل أي تعديل
        byte[] xmlBytes = Encoding.UTF8.GetBytes(ublXml);

        using SHA256 sha256 = SHA256.Create();
        byte[] hashBytes = sha256.ComputeHash(xmlBytes);

        // تُرسل التجزئة عادة بصيغة Base64 في جسم الطلب
        return Convert.ToBase64String(hashBytes);
    }
}

// مثال على الاستخدام
string ublXml = System.IO.File.ReadAllText("invoice.xml", Encoding.UTF8);
string invoiceHash = InvoiceHasher.ComputeInvoiceHash(ublXml);
Console.WriteLine($"Invoice Hash (Base64): {invoiceHash}");

انتبه إلى نقطة دقيقة تكلّف المطوّرين ساعات تصحيح. التجزئة تُحسب على بايتات المستند كما هي بالضبط. أي تغيير ولو في مسافة بيضاء واحدة أو في ترتيب السمات داخل الـ XML ينتج تجزئة مختلفة تمامًا، فتردّ البوابة الفاتورة. لذلك احسب التجزئة على نفس البايتات التي سترسلها، ولا تعِد تنسيق الـ XML بعد حساب التجزئة.

هنا يظهر فخّ شائع في ‎.NET‎ تحديدًا. كثير من المطوّرين يحمّلون الـ XML في كائن XmlDocument أو XDocument لمعالجته، ثم يعيدون كتابته نصًا. هذه العملية قد تغيّر الترميز، أو تضيف إعلان XML، أو تعيد ترتيب مساحات الأسماء (Namespaces)، فتنتج بايتات مختلفة عن الأصل. القاعدة الآمنة: عامل مستند الفاتورة بعد بنائه كسلسلة بايتات ثابتة. احسب تجزئته وارمّزه وأرسله من نفس المخزن البايتي، ولا تمرّره عبر أي معالج XML يعيد تشكيله.

السبب الجوهري أن خوارزمية SHA-256 حسّاسة لكل بايت. تغيير بايت واحد يقلب التجزئة بالكامل بفعل خاصية الانهيار (Avalanche Effect). هذا بالضبط ما يجعل التجزئة مفيدة لإثبات سلامة المستند، لكنه أيضًا ما يجعل أي تعديل عرَضي كارثيًا. فكّر في التجزئة كبصمة رقمية للمستند: بصمتان متطابقتان تعنيان مستندين متطابقين بايتًا ببايت، وأي اختلاف ولو ضئيل ينتج بصمة مغايرة.

للتحقق العملي أثناء التطوير، احفظ نسخة من البايتات التي حسبت عليها التجزئة، وقارنها بالبايتات التي أرسلتها فعلًا. إن اختلفتا، فقد تسلّل تحويل في مكان ما من خط المعالجة. هذا الفحص البسيط يوفّر عليك ساعات من تتبّع رفض غامض من البوابة.

المرحلة الثالثة: ترميز مستند UBL بصيغة Base64

جسم الطلب المرسل إلى منصة فاتورة يحمل مستند الفاتورة مرمّزًا بصيغة Base64. السبب أن الـ XML قد يحتوي على رموز خاصة تكسر بنية JSON إن أُرسلت كما هي. الترميز بصيغة Base64 يحوّل المستند إلى سلسلة آمنة ضمن JSON.

نستخدم نفس دالة Convert.ToBase64String التي رأيناها، لكن هذه المرة على بايتات المستند الكامل:

ترميز الـ XML بصيغة Base64 بلغة C#

using System;
using System.Text;

public static class UblEncoder
{
    // يرمّز مستند UBL XML بصيغة Base64 لوضعه في جسم JSON
    public static string EncodeInvoice(string ublXml)
    {
        byte[] xmlBytes = Encoding.UTF8.GetBytes(ublXml);
        return Convert.ToBase64String(xmlBytes);
    }
}

// مثال على الاستخدام
string ublXml = System.IO.File.ReadAllText("invoice.xml", Encoding.UTF8);
string invoiceBase64 = UblEncoder.EncodeInvoice(ublXml);
string invoiceHash = InvoiceHasher.ComputeInvoiceHash(ublXml);

// جسم الطلب الذي سترسله إلى منصة فاتورة
var requestBody = new
{
    invoiceHash = invoiceHash,
    uuid = Guid.NewGuid().ToString(),
    invoice = invoiceBase64
};

لاحظ أننا حسبنا التجزئة ورمّزنا المستند من نفس المتغير ublXml ومن نفس البايتات. هذا يضمن تطابق التجزئة مع المحتوى المرسل. الحقل uuid معرّف فريد عالمي للفاتورة، نولّده بـ Guid.NewGuid()، ويجب أن يطابق المعرّف داخل الـ XML نفسه.

المرحلة الرابعة: إرسال الفاتورة عبر HttpClient إلى المسح والإبلاغ

تتعامل منصة فاتورة مع نوعين من الفواتير لكل منهما نقطة نهاية مختلفة. الفواتير الضريبية الموجّهة للمنشآت (B2B) تمرّ عبر نقطة المسح (Clearance)، إذ تتحقق منها الهيئة وتختمها قبل تسليمها للمشتري. الفواتير الضريبية المبسّطة الموجّهة للأفراد (B2C) تُرسل عبر نقطة الإبلاغ (Reporting) خلال أربع وعشرين ساعة من إصدارها.

في C# نبني عميل HttpClient واحدًا نعيد استخدامه، ونضيف الترويسات المطلوبة، ثم نرسل جسم JSON. الكود التالي يرسل فاتورة إلى نقطة المسح:

إرسال الفاتورة إلى نقطة المسح بلغة C#

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

public class FatooraClient
{
    private readonly HttpClient _http;
    private const string ClearanceUrl =
        "https://gw-fatoora.zatca.gov.sa/e-invoicing/core/invoices/clearance/single";

    public FatooraClient(HttpClient http)
    {
        _http = http;
    }

    public async Task<string> ClearInvoiceAsync(
        string csid, string secret, string invoiceHash, string uuid, string invoiceBase64)
    {
        var payload = new
        {
            invoiceHash,
            uuid,
            invoice = invoiceBase64
        };

        string json = JsonSerializer.Serialize(payload);

        using var request = new HttpRequestMessage(HttpMethod.Post, ClearanceUrl);
        request.Headers.Authorization = AuthenticationHeaderValue.Parse(
            FatooraAuth.BuildBasicHeader(csid, secret));
        request.Headers.Add("Accept-Version", "V2");
        request.Headers.Add("Clearance-Status", "1");
        request.Content = new StringContent(json, Encoding.UTF8, "application/json");

        HttpResponseMessage response = await _http.SendAsync(request);
        string body = await response.Content.ReadAsStringAsync();

        // 200 يعني تم المسح بنجاح، 202 يعني مسح مع ملاحظات (Warnings)
        if (!response.IsSuccessStatusCode)
        {
            throw new FatooraException((int)response.StatusCode, body);
        }

        return body;
    }
}

الترويسة Accept-Version تحدد إصدار الواجهة، والترويسة Clearance-Status بقيمة 1 تطلب مسحًا فعليًا. لإرسال فاتورة مبسّطة عبر نقطة الإبلاغ، تستبدل المسار بـ /invoices/reporting/single وتزيل ترويسة المسح. البنية نفسها، تتغير نقطة النهاية فقط.

يستحق الفرق بين المسح والإبلاغ توضيحًا عمليًا يؤثر مباشرة في تصميم تطبيقك. المسح عملية متزامنة (Synchronous): ترسل الفاتورة وتنتظر ختم الهيئة قبل أن تسلّمها للمشتري. هذا يعني أن المشتري لا يستلم فاتورته إلا بعد ردّ البوابة. لذلك يجب أن يكون زمن الاستجابة محسوبًا في تجربة المستخدم، وأن تتعامل مع حالة بطء البوابة بأناقة. الإبلاغ بطبيعته أكثر تساهلًا في التوقيت، إذ تملك مهلة حتى أربع وعشرين ساعة لإرسال الفاتورة المبسّطة بعد إصدارها، وهو ما يسمح لك بتجميع الفواتير وإرسالها على دفعات.

هذا الفرق يقترح معماريتين مختلفتين. في حالة المسح، يكون الإرسال جزءًا من مسار الطلب الحي، فتهتم بزمن الاستجابة والمهلة. في حالة الإبلاغ، يمكنك وضع الفواتير في طابور (Queue) ومعالجتها بعملية خلفية، فتعزل بطء البوابة عن تجربة نقطة البيع. في ‎.NET‎ تبني هذه العملية الخلفية باستخدام BackgroundService أو خدمة مستضافة (Hosted Service) تسحب الفواتير من الطابور وترسلها بإيقاع منتظم.

نقطة عملية أخرى: لا ترسل الفاتورة نفسها مرتين على نقطتين مختلفتين. نوع الفاتورة يحدد المسار. الفاتورة الضريبية الكاملة (B2B) تذهب للمسح حصرًا، والفاتورة المبسّطة (B2C) تذهب للإبلاغ حصرًا. تحديد النوع يأتي من حقل داخل مستند UBL نفسه، لا من قرار في كودك. اقرأ النوع من المستند ووجّه الطلب وفقه، فهذا يضمن اتساق المسار مع محتوى الفاتورة.

المرحلة الخامسة: تحليل الاستجابة بـ System.Text.Json

تعيد منصة فاتورة استجابة JSON تحمل حالة المعالجة ونتيجة التحقق. في حالة B2B يعيد الردّ الفاتورة المختومة (Cleared Invoice) مرمّزة بصيغة Base64، وهي النسخة المعتمدة التي تسلّمها للمشتري. نقرأ هذه الحقول باستخدام System.Text.Json.

قراءة حقول الاستجابة بلغة C#

using System;
using System.Text.Json;

public class ClearanceResult
{
    public string Status { get; set; }
    public string ClearedInvoiceBase64 { get; set; }
}

public static class ResponseParser
{
    public static ClearanceResult ParseClearance(string jsonBody)
    {
        using JsonDocument doc = JsonDocument.Parse(jsonBody);
        JsonElement root = doc.RootElement;

        var result = new ClearanceResult();

        // حالة المسح: CLEARED أو NOT_CLEARED
        if (root.TryGetProperty("clearanceStatus", out JsonElement statusEl))
        {
            result.Status = statusEl.GetString();
        }

        // الفاتورة المختومة مرمّزة Base64
        if (root.TryGetProperty("clearedInvoice", out JsonElement invoiceEl))
        {
            result.ClearedInvoiceBase64 = invoiceEl.GetString();
        }

        return result;
    }
}

// مثال على الاستخدام
ClearanceResult result = ResponseParser.ParseClearance(responseBody);
if (result.Status == "CLEARED")
{
    byte[] clearedXml = Convert.FromBase64String(result.ClearedInvoiceBase64);
    System.IO.File.WriteAllBytes("cleared-invoice.xml", clearedXml);
}

نستخدم TryGetProperty بدل الوصول المباشر للحقل، لأن بنية الاستجابة قد تختلف بين النجاح والرفض. هذا الأسلوب يحميك من استثناء عند غياب حقل متوقع. بعد قراءة الفاتورة المختومة، نفك ترميز Base64 بـ Convert.FromBase64String ونحفظ النسخة المعتمدة.

تحمل استجابة منصة فاتورة أكثر من حالة المسح. تجد فيها عادة قوائم بالتحذيرات (Warnings) والأخطاء (Errors)، كل منها بمعرّف ورسالة. التحذيرات لا تمنع قبول الفاتورة، لكنها تشير إلى نقاط يجب أن تعالجها قبل أن تتحول إلى أخطاء في إصدار لاحق من الواجهة. لذلك لا تتجاهلها. اقرأ مصفوفة التحذيرات وسجّلها، فهي إنذار مبكّر يقيك مفاجآت مستقبلية.

في تطبيق ‎.NET‎ منظّم، تحوّل هذه القوائم إلى نماذج (Models) واضحة بدل التعامل مع JsonElement خامًا في كل مكان. عرّف صنفًا للتحذير وصنفًا للخطأ، وحمّل إليهما القيم مرة واحدة عند تحليل الاستجابة. هذا يجعل بقية كودك يتعامل مع كائنات مكتوبة بقوة (Strongly Typed) بدل التنقيب في شجرة JSON. الفائدة مزدوجة: كود أوضح، وأخطاء تُكتشف وقت الترجمة لا وقت التشغيل.

التسجيل والمراقبة في تكامل الإنتاج

التكامل مع جهة حكومية يحتاج سجلًّا يمكن الرجوع إليه عند أي نزاع أو تدقيق. سجّل لكل فاتورة معرّفها الفريد (UUID)، وتجزئتها، ورمز الاستجابة، ووقت الإرسال، ونتيجة المعالجة. هذا السجلّ ليس رفاهية، بل ضرورة تشغيلية تثبت أنك أرسلت الفاتورة وأن الهيئة قبلتها.

في ‎.NET‎ تستخدم واجهة ILogger القياسية لتدوين هذه الأحداث. اربط كل سجلّ بمعرّف الفاتورة حتى تتمكن من تتبّع رحلتها كاملة عبر السجلّات. عند حدوث رفض، يصبح هذا الربط هو ما يسمح لك بالعثور على الطلب الأصلي والاستجابة معًا في لحظات، بدل البحث الأعمى في ملفات السجلّ.

احذر من تسجيل البيانات الحساسة. لا تكتب CSID ولا السرّ ولا ترويسة Authorization في السجلّات أبدًا. سجّل معرّفات ورموز حالة ونتائج، لا بيانات اعتماد. تسرّب الأسرار عبر السجلّات خطأ أمني متكرر، إذ تُجمع السجلّات غالبًا في أنظمة مركزية يطّلع عليها كثيرون. عامل السجلّ كأنه قابل للقراءة من خارج فريقك، واكتب فيه ما يصح أن يراه الجميع فقط.

أضف إلى التسجيل مقاييس تشغيلية تراقب صحة التكامل: نسبة الفواتير المقبولة، متوسط زمن الاستجابة، عدد إعادات المحاولة، توزيع رموز الأخطاء. هذه المقاييس تكشف تدهور الخدمة قبل أن يلاحظه المستخدمون. في ‎.NET‎ تجمعها عبر عدّادات (Counters) وتصدّرها لنظام مراقبة، فتحوّل تكاملك من صندوق أسود إلى نظام مرئيّ تفهم سلوكه لحظة بلحظة.

المرحلة السادسة: معالجة الأخطاء وإعادة المحاولة

أي تكامل إنتاجي جاد يحتاج طبقة معالجة أخطاء واضحة. منصة فاتورة تردّ برموز حالة مختلفة، ولكل منها معنى ومعالجة. لا تعامل كل خطأ بالطريقة نفسها. الجدول التالي يلخّص أهم الرموز:

القاعدة الحاكمة: أعِد المحاولة فقط على أخطاء الخادم المؤقتة (500 و503 ومهلة الاتصال). لا تعِد المحاولة أبدًا على 400 أو 401، لأن تكرار طلب خاطئ يبقى خاطئًا ويهدر الموارد. الكود التالي يميّز بين الحالتين:

صنف الاستثناء وحلقة إعادة المحاولة بلغة C#

using System;
using System.Net.Http;
using System.Threading.Tasks;

public class FatooraException : Exception
{
    public int StatusCode { get; }
    public string ResponseBody { get; }

    public FatooraException(int statusCode, string responseBody)
        : base($"Fatoora API returned {statusCode}")
    {
        StatusCode = statusCode;
        ResponseBody = responseBody;
    }

    // الأخطاء القابلة لإعادة المحاولة فقط
    public bool IsRetryable => StatusCode == 500 || StatusCode == 503;
}

public static class RetryPolicy
{
    public static async Task<T> ExecuteAsync<T>(Func<Task<T>> action, int maxAttempts = 4)
    {
        int attempt = 0;
        while (true)
        {
            attempt++;
            try
            {
                return await action();
            }
            catch (FatooraException ex) when (ex.IsRetryable && attempt < maxAttempts)
            {
                // تراجع أُسّي: 1، 2، 4 ثوانٍ
                int delaySeconds = (int)Math.Pow(2, attempt - 1);
                await Task.Delay(TimeSpan.FromSeconds(delaySeconds));
            }
            catch (HttpRequestException) when (attempt < maxAttempts)
            {
                // مشكلة شبكة أو مهلة اتصال: أعِد المحاولة
                int delaySeconds = (int)Math.Pow(2, attempt - 1);
                await Task.Delay(TimeSpan.FromSeconds(delaySeconds));
            }
        }
    }
}

// مثال على الاستخدام مع العميل
string body = await RetryPolicy.ExecuteAsync(() =>
    client.ClearInvoiceAsync(csid, secret, invoiceHash, uuid, invoiceBase64));

الحلقة تطبّق تراجعًا أُسّيًا (Exponential Backoff): تنتظر ثانية واحدة بعد المحاولة الأولى، ثم ثانيتين، ثم أربعًا. هذا يمنح خادم الهيئة وقتًا للتعافي ويتجنّب إغراقه بطلبات متتالية. الشرط when (ex.IsRetryable) يضمن أننا نعيد المحاولة على الأخطاء المؤقتة فقط.

إن كنت تبني نظامًا إنتاجيًا، فمكتبة Polly خيار ناضج لإدارة سياسات إعادة المحاولة وقاطع الدائرة (Circuit Breaker) في ‎.NET‎. تغنيك عن كتابة منطق التراجع يدويًا، وتوفّر سياسات جاهزة ومختبرة. لكن المبدأ يبقى نفسه: أعِد المحاولة على الأخطاء العابرة فقط.

تجميع التكامل الكامل من طرف إلى طرف

الآن نجمع المراحل الست في تدفّق واحد. السيناريو الكامل: نقرأ مستند UBL، نحسب تجزئته، نرمّزه بصيغة Base64، نبني الطلب، نرسله عبر HttpClient مع إعادة المحاولة، ثم نحلّل الاستجابة. الكود التالي يربط كل شيء:

التدفّق الكامل بلغة C#

using System;
using System.IO;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

public class Program
{
    public static async Task Main()
    {
        // 1) قراءة بيانات الاعتماد من البيئة (لا تكتبها في الكود)
        string csid = Environment.GetEnvironmentVariable("FATOORA_CSID");
        string secret = Environment.GetEnvironmentVariable("FATOORA_SECRET");

        // 2) قراءة مستند الفاتورة
        string ublXml = File.ReadAllText("invoice.xml", Encoding.UTF8);

        // 3) حساب التجزئة وترميز المستند من نفس البايتات
        string invoiceHash = InvoiceHasher.ComputeInvoiceHash(ublXml);
        string invoiceBase64 = UblEncoder.EncodeInvoice(ublXml);
        string uuid = Guid.NewGuid().ToString();

        // 4) إنشاء عميل HttpClient واحد قابل لإعادة الاستخدام
        using var http = new HttpClient
        {
            Timeout = TimeSpan.FromSeconds(30)
        };
        var client = new FatooraClient(http);

        try
        {
            // 5) الإرسال مع إعادة المحاولة على الأخطاء العابرة
            string responseBody = await RetryPolicy.ExecuteAsync(() =>
                client.ClearInvoiceAsync(csid, secret, invoiceHash, uuid, invoiceBase64));

            // 6) تحليل الاستجابة
            ClearanceResult result = ResponseParser.ParseClearance(responseBody);
            Console.WriteLine($"Clearance status: {result.Status}");

            if (result.Status == "CLEARED")
            {
                byte[] clearedXml = Convert.FromBase64String(result.ClearedInvoiceBase64);
                File.WriteAllBytes("cleared-invoice.xml", clearedXml);
                Console.WriteLine("تم حفظ الفاتورة المختومة بنجاح.");
            }
        }
        catch (FatooraException ex)
        {
            // خطأ نهائي غير قابل لإعادة المحاولة
            Console.Error.WriteLine($"فشل الإرسال برمز {ex.StatusCode}: {ex.ResponseBody}");
        }
    }
}

لاحظ نقطة مهمة في إدارة الموارد. أنشأنا HttpClient واحدًا وأعدنا استخدامه. إنشاء عميل جديد لكل طلب يستنزف منافذ الشبكة (Socket Exhaustion) في الأنظمة عالية الحركة. في تطبيقات ‎.NET‎ الحديثة، يُفضَّل استخدام IHttpClientFactory لإدارة دورة حياة العميل بكفاءة عبر حقن الاعتماديات (Dependency Injection).

أخطاء شائعة في تكامل ‎.NET‎ وكيف تتجنّبها

بعد بناء التكامل، احذر من ثلاثة أخطاء تتكرر كثيرًا في مشاريع C#. الأول هو إعادة تنسيق الـ XML بعد حساب التجزئة. أي أداة تنسيق تغيّر المسافات أو ترتيب السمات تكسر التطابق بين التجزئة والمحتوى. احسب التجزئة على البايتات النهائية التي سترسلها.

الثاني هو الخلط بين ترميز UTF-8 وترميزات أخرى. استخدم Encoding.UTF8 صراحة عند القراءة وعند حساب التجزئة وعند الترميز. الاعتماد على الترميز الافتراضي للنظام ينتج تجزئة مختلفة على أجهزة مختلفة.

الثالث هو معاملة الخطأ 401 كأنه خطأ عابر وإعادة المحاولة عليه. الخطأ 401 يعني أن بيانات المصادقة خاطئة، وتكرار الطلب لن يصلحها بل قد يؤدي إلى حظر مؤقت. عالج 401 بمراجعة CSID والسرّ، لا بإعادة المحاولة.

كيف يساعدك قيود

كل ما سبق يشرح كيف تبني التكامل بنفسك من الصفر بلغة C#. هذا مسار مناسب لفِرَق تقنية تريد التحكم الكامل في الطبقة المنخفضة. لكن بناء هذا التكامل وصيانته مع تغيّر متطلبات الهيئة يستهلك وقت فريقك.

قيود يربط منشأتك بمنصة فاتورة تلقائيًا. يصدر فواتيرك الإلكترونية متوافقة مع متطلبات هيئة الزكاة والضريبة والجمارك للمرحلة الثانية من الفوترة الإلكترونية، ويتولى التوقيع والمسح والإبلاغ دون أن تكتب سطرًا واحدًا من الكود. تحصل على نتيجة هذا الدليل كاملًا، جاهزة وموثوقة، عبر واجهة بسيطة.

أدلّة المطوّرين ذات الصلة

هذا الدليل جزء من سلسلة أمثلة التكامل في مركز المطوّرين. إن كنت تعمل بلغة أخرى، فلكل لغة دليلها بالبنية نفسها. ابدأ من الأساس التقني في دليل المصادقة في واجهة الفوترة، ثم تعرّف على نقاط نهاية API لمنصة فاتورة، وأخيرًا تعمّق في تفاصيل إرسال الفاتورة عبر API. تشكّل هذه الأدلة الثلاثة معًا الأساس الذي تبني عليه أي تكامل بلغة ‎.NET‎ أو غيرها.

للصورة الكاملة عن الفوترة الإلكترونية ومتطلبات الهيئة، ارجع إلى دليل الفاتورة الإلكترونية من قيود.

قبل أن تنقل هذا التكامل إلى الإنتاج، راجع قائمة تحقق قصيرة. هل تقرأ CSID والسرّ من خزنة أسرار آمنة لكل بيئة؟ هل تحسب التجزئة على نفس البايتات التي ترسلها دون أي إعادة تنسيق؟ هل تعيد المحاولة على الأخطاء العابرة فقط وتتوقف فورًا عند 400 و401؟ هل تسجّل معرّف كل فاتورة ورمز استجابتها دون تسريب بيانات الاعتماد؟ هل تعيد استخدام عميل HttpClient بدل إنشائه لكل طلب؟ كل بند من هذه البنود يمثّل فرقًا بين تكامل تجريبي وتكامل إنتاجي صامد. أجب عنها جميعًا بنعم قبل أن تطلق نظامك.

أخيرًا، تذكّر أن متطلبات الهيئة تتطوّر مع الزمن، وأن أي تكامل تبنيه بنفسك يحتاج صيانة مستمرة لمواكبة هذه التغيّرات. هذا العبء التشغيلي حقيقي، وهو السبب الذي يدفع كثيرًا من المنشآت لاختيار حل يتولّى عنها هذه المسؤولية. سواء بنيت التكامل بنفسك أو اعتمدت على قيود، فالأساس الذي شرحناه هنا يبقى مرجعك لفهم ما يجري خلف الكواليس في كل فاتورة إلكترونية تصدرها منشأتك.