ربط زاتكا بـ Laravel
طلب HTTP واحد من Laravel (DB::transaction + Http): ماثل يبني الفاتورة ويوقّعها ويرسلها للهيئة، ويرجّع رد الهيئة والـ XML القانوني والـ PDF مع رمز QR.
١. جرّبه الحين (بدون مفتاح)
// composer require matheel/matheel-php
require 'vendor/autoload.php';
$matheel = new Matheel\Matheel(getenv('MATHEEL_KEY') ?: null); // the sandbox needs no key
$res = $matheel->fileInvoice(['environment' => 'sandbox', 'pdf' => true, 'invoice' => [
'type' => 'simplified', 'line_items' => [['name' => 'قهوة', 'quantity' => 2, 'price' => '50.00']]]]);
echo $res['status']; // reported, plus qr, pdf, invoice_xml
// After a payment: $matheel->fileWithStore($store, $invoice) keeps the device chain for you
٢. الدالة الجاهزة بعد الدفع
تقفل صف الجهاز (عشان دفعتين بنفس اللحظة ما يكسرون السلسلة)، ترسل الفاتورة مع "pdf": true، وتحفظ device_token الجديد. أي رد غير 200 يرجّع الـ transaction والمفتاح القديم يظل صالح.
// DB::transaction rolls back on any exception; lockForUpdate() is SELECT … FOR UPDATE; throw() fails on non-2xx.
use Illuminate\Support\Facades\{DB, Http};
function matheel_invoice(array $items): array {
return DB::transaction(function () use ($items) {
$device = DB::table('matheel_device')->where('id', 1)->lockForUpdate()->first();
$res = Http::withToken(env('MATHEEL_KEY'))->timeout(60)
->post('https://matheel.app/api/v1/invoices', ['device_token' => $device->token, 'pdf' => true,
'invoice' => ['type' => 'simplified', 'line_items' => $items]])
->throw()->json();
DB::table('matheel_device')->where('id', 1)->update(['token' => $res['device_token']]);
return $res; // base64_decode($res['pdf']) is the PDF
});
}
أو بمكتبة ماثل الرسمية: composer require matheel/matheel-php، وfileWithStore تسوي نفس الشي: تقرأ المفتاح وتحفظه في متجرك، وتعيد المحاولة لحالها لو رجع 409.
٣. للإنتاج
- سجّل جهازك مرة (مفتاح الجهاز أو لينك التفعيل) وحط
device_tokenفي جدولmatheel_device. - لو المبلغ اللي معك شامل الضريبة، أرسل
"prices_include_vat": true. - احفظ
invoice_xml(القانوني) وpdfمع الطلب، والتطبيق يعرض الـ PDF من سيرفرك.
أسئلة شائعة
أحتاج مكتبة Laravel خاصة بزاتكا؟
لا. ماثل API عادي بـ JSON: طلب HTTP واحد. التوقيع والـ XML والشهادة والإرسال للهيئة كلها عند ماثل. وفيه مكتبة رسمية لو تبيها: composer require matheel/matheel-php
وين أحفظ مفتاح الجهاز؟
صف واحد في قاعدة بياناتك (جدول matheel_device). بعد كل رد 200 احفظ device_token الجديد في نفس الـ transaction.
أجرّب قبل الاشتراك؟
إيه، على بيئة المطورين بدون مفتاح: الطلب تحت يرجّع رد الهيئة الحقيقي والـ PDF.