ربط WooCommerce مع زاتكا
WooCommerce (متجر إلكتروني) يبلغك لما الطلب يندفع، وماثل يحوّل هالدفعة لفاتورة زاتكا مرسلة ومقبولة، مع PDF عربي وإنجليزي فيه رمز QR.
عندك إضافة جاهزة: نزّل إضافة ماثل لووكومرس وفعّلها، وما تحتاج الكود تحت. الكود للي يبي يبني الربط بنفسه.
الحدث اللي تستمع له
woocommerce_payment_complete (PHP action, args: $order_id, $transaction_id). Outside WordPress: webhook topic order.updated, then check status processing/completed and date_paid
التسجيل
In-site: add_action('woocommerce_payment_complete', ...) in a small plugin. External server: WooCommerce > Settings > Advanced > Webhooks > Add webhook (name, status, topic, delivery URL, secret)
التحقق إن الطلب جاي من WooCommerce
In-site action: none needed (runs inside WordPress). Webhook: header X-WC-Webhook-Signature = base64 HMAC-SHA256 of the payload, keyed with the webhook secret (defaults to the API user's consumer secret if blank)
المبلغ والبنود
- المبلغ:
REST/webhook order: total (grand total), total_tax; line_items[].total (line total after discounts) and line_items[].total_tax. PHP: $order->get_item_total($item, false) = unit price after discounts, excluding tax - البنود:
PHP: $order->get_items() -> $item->get_name(), $item->get_quantity(). REST/webhook: line_items[].name, line_items[].quantity - إيميل العميل:
billing.email (PHP: $order->get_billing_email())
لو المبلغ شامل الضريبة (وهو الغالب)، أرسله زي ما هو مع "prices_include_vat": true.
الكود
يستقبل الحدث، يتحقق منه، ويستدعي matheel_invoice(items): الدالة الجاهزة اللي تقفل صف الجهاز وترسل الفاتورة وتحفظ المفتاح الجديد.
<?php
// Small plugin: fires once a gateway marks the order paid (WC_Order::payment_complete).
add_action('woocommerce_payment_complete', function ($order_id) {
$order = wc_get_order($order_id);
$items = [];
foreach ($order->get_items() as $item) {
$items[] = [
'name' => $item->get_name(),
'quantity' => (string) $item->get_quantity(),
// Unit price after discounts, without tax ($inc_tax = false).
'price' => number_format($order->get_item_total($item, false, true), 2, '.', ''),
];
}
$res = matheel_invoice($items);
$order->add_order_note('Matheel: ' . $res['status']);
});
ملاحظات
prices_include_tax (REST, read-only) says whether shop prices were entered with tax; get_item_total(..., false) returns the price without tax either way. get_items() returns product lines only: shipping_lines and fee_lines are separate, so add them as their own items if the customer paid for them. The REST docs list core topics order.created/order.updated/order.deleted and custom action.<hook> topics; there is no dedicated 'order paid' topic. Offline gateways (bank transfer, cheque, COD) may never call payment_complete (unverified): for them hook the order status change instead. The webhook docs page does not state the header or algorithm; they come from the REST API docs.
أسئلة شائعة
هل WooCommerce يرسل الفواتير لزاتكا بنفسه؟
WooCommerce متجر إلكتروني، وربطه مع الهيئة يكون عن طريق خدمة مثل ماثل: كل دفعة ناجحة تتحول لفاتورة مرسلة للهيئة.
لازم أعدّل الأسعار عشان الضريبة؟
لا. أرسل المبلغ اللي دفعه العميل مع "prices_include_vat": true، وماثل يطلّع الضريبة ويخلّي المبلغ المستحق في الفاتورة نفس المدفوع.
وش يصير لو جت دفعتين بنفس الثانية؟
فواتير الجهاز تمشي ورا بعض. اقفل صف الجهاز وقت الإرسال (موجود في الدالة الجاهزة)، وماثل يرفض أي نسخة قديمة من مفتاح الجهاز بـ 409 عشان السلسلة ما تنكسر.