ربط زاتكا بـ 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.

٣. للإنتاج

أسئلة شائعة

أحتاج مكتبة PHP خاصة بزاتكا؟

لا. ماثل API عادي بـ JSON: طلب HTTP واحد. التوقيع والـ XML والشهادة والإرسال للهيئة كلها عند ماثل. وفيه مكتبة رسمية لو تبيها: composer require matheel/matheel-php

وين أحفظ مفتاح الجهاز؟

صف واحد في قاعدة بياناتك (جدول matheel_device). بعد كل رد 200 احفظ device_token الجديد في نفس الـ transaction.

أجرّب قبل الاشتراك؟

إيه، على بيئة المطورين بدون مفتاح: الطلب تحت يرجّع رد الهيئة الحقيقي والـ PDF.

جرّبه الحين على بيئة المطورين

بدون مفتاح ولا تسجيل: الرد رد الهيئة الحقيقي، ومعه الفاتورة PDF عربي وإنجليزي ورمز QR.

ابدأ الأسعار