ربط 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)

المبلغ والبنود

لو المبلغ شامل الضريبة (وهو الغالب)، أرسله زي ما هو مع "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 عشان السلسلة ما تنكسر.

المصادر الرسمية: developer.woocommerce.com/docs/best-practices/urls-and-routi · woocommerce.github.io/woocommerce-rest-api-docs/#webhooks · woocommerce.github.io/woocommerce-rest-api-docs/#order-prope · github.com/woocommerce/woocommerce/blob/trunk/plugins/woocom · github.com/woocommerce/woocommerce/blob/trunk/plugins/woocom

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

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

ابدأ الأسعار