ربط زاتكا بـ PHP
طلب HTTP واحد من PHP (cURL + PDO): ماثل يبني الفاتورة ويوقّعها ويرسلها للهيئة، ويرجّع رد الهيئة والـ 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 والمفتاح القديم يظل صالح.
<?php
// Call after the payment gateway confirms the payment. Returns Matheel's response (pdf, invoice_xml, qr…).
function matheel_invoice(PDO $db, array $items): array {
$db->beginTransaction();
// Row lock: two payments in the same second file one after the other, never on the same token.
$token = $db->query("SELECT token FROM matheel_device WHERE id = 1 FOR UPDATE")->fetchColumn();
$ch = curl_init("https://matheel.app/api/v1/invoices");
curl_setopt_array($ch, [
CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 60,
CURLOPT_HTTPHEADER => ["Content-Type: application/json", "Authorization: Bearer " . getenv("MATHEEL_KEY")],
CURLOPT_POSTFIELDS => json_encode(["device_token" => $token, "pdf" => true,
"invoice" => ["type" => "simplified", "line_items" => $items]]),
]);
$res = json_decode(curl_exec($ch), true);
if (curl_getinfo($ch, CURLINFO_HTTP_CODE) !== 200) { $db->rollBack(); throw new RuntimeException(json_encode($res)); }
$db->prepare("UPDATE matheel_device SET token = ? WHERE id = 1")->execute([$res["device_token"]]);
$db->commit();
return $res;
}
// Example: after Telr says the payment is paid.
$res = matheel_invoice($db, [["name" => "تجديد إقامة", "quantity" => 1, "price" => "130.43"]]);
file_put_contents("invoices/{$orderId}.pdf", base64_decode($res["pdf"]));
file_put_contents("invoices/{$orderId}.xml", base64_decode($res["invoice_xml"]));
أو بمكتبة ماثل الرسمية: composer require matheel/matheel-php، وfileWithStore تسوي نفس الشي: تقرأ المفتاح وتحفظه في متجرك، وتعيد المحاولة لحالها لو رجع 409.
٣. للإنتاج
- سجّل جهازك مرة (مفتاح الجهاز أو لينك التفعيل) وحط
device_tokenفي جدولmatheel_device. - لو المبلغ اللي معك شامل الضريبة، أرسل
"prices_include_vat": true. - احفظ
invoice_xml(القانوني) وpdfمع الطلب، والتطبيق يعرض الـ PDF من سيرفرك.
أسئلة شائعة
أحتاج مكتبة PHP خاصة بزاتكا؟
لا. ماثل API عادي بـ JSON: طلب HTTP واحد. التوقيع والـ XML والشهادة والإرسال للهيئة كلها عند ماثل. وفيه مكتبة رسمية لو تبيها: composer require matheel/matheel-php
وين أحفظ مفتاح الجهاز؟
صف واحد في قاعدة بياناتك (جدول matheel_device). بعد كل رد 200 احفظ device_token الجديد في نفس الـ transaction.
أجرّب قبل الاشتراك؟
إيه، على بيئة المطورين بدون مفتاح: الطلب تحت يرجّع رد الهيئة الحقيقي والـ PDF.