ربط زاتكا بـ C# / .NET
طلب HTTP واحد من C# / .NET (HttpClient + Npgsql): ماثل يبني الفاتورة ويوقّعها ويرسلها للهيئة، ويرجّع رد الهيئة والـ XML القانوني والـ PDF مع رمز QR.
١. جرّبه الحين (بدون مفتاح)
// dotnet new console, then Program.cs:
using System.Net.Http.Json; using System.Text.Json;
using var http = new HttpClient();
var r = await http.PostAsJsonAsync("https://matheel.app/api/v1/invoices", new {
environment = "sandbox", pdf = true, invoice = new {
type = "simplified", line_items = new[] { new { name = "قهوة", quantity = 2, price = "50.00" } } } });
var res = await r.Content.ReadFromJsonAsync<JsonElement>();
Console.WriteLine(res.GetProperty("status")); // reported
٢. الدالة الجاهزة بعد الدفع
تقفل صف الجهاز (عشان دفعتين بنفس اللحظة ما يكسرون السلسلة)، ترسل الفاتورة مع "pdf": true، وتحفظ device_token الجديد. أي رد غير 200 يرجّع الـ transaction والمفتاح القديم يظل صالح.
// Npgsql + HttpClient. Same flow on SQL Server: SELECT … WITH (UPDLOCK, ROWLOCK).
public async Task<JsonElement> MatheelInvoice(NpgsqlConnection db, object[] items) {
await using var tx = await db.BeginTransactionAsync();
var token = (string)await new NpgsqlCommand("SELECT token FROM matheel_device WHERE id = 1 FOR UPDATE", db, tx).ExecuteScalarAsync();
http.DefaultRequestHeaders.Authorization = new("Bearer", Environment.GetEnvironmentVariable("MATHEEL_KEY"));
var r = await http.PostAsJsonAsync("https://matheel.app/api/v1/invoices",
new { device_token = token, pdf = true, invoice = new { type = "simplified", line_items = items } });
var res = await r.Content.ReadFromJsonAsync<JsonElement>();
if (!r.IsSuccessStatusCode) throw new Exception(res.ToString()); // tx rolls back on dispose
var up = new NpgsqlCommand("UPDATE matheel_device SET token = @t WHERE id = 1", db, tx);
up.Parameters.AddWithValue("t", res.GetProperty("device_token").GetString());
await up.ExecuteNonQueryAsync();
await tx.CommitAsync();
return res; // Convert.FromBase64String(res.GetProperty("pdf").GetString()) is the PDF
}
٣. للإنتاج
- سجّل جهازك مرة (مفتاح الجهاز أو لينك التفعيل) وحط
device_tokenفي جدولmatheel_device. - لو المبلغ اللي معك شامل الضريبة، أرسل
"prices_include_vat": true. - احفظ
invoice_xml(القانوني) وpdfمع الطلب، والتطبيق يعرض الـ PDF من سيرفرك.
أسئلة شائعة
أحتاج مكتبة C# / .NET خاصة بزاتكا؟
لا. ماثل API عادي بـ JSON: طلب HTTP واحد. التوقيع والـ XML والشهادة والإرسال للهيئة كلها عند ماثل.
وين أحفظ مفتاح الجهاز؟
صف واحد في قاعدة بياناتك (جدول matheel_device). بعد كل رد 200 احفظ device_token الجديد في نفس الـ transaction.
أجرّب قبل الاشتراك؟
إيه، على بيئة المطورين بدون مفتاح: الطلب تحت يرجّع رد الهيئة الحقيقي والـ PDF.