ربط Zid مع زاتكا

من فريق ماثل · آخر تحديث

Zid (متجر إلكتروني) يبلغك لما الطلب يندفع، وماثل يحوّل هالدفعة لفاتورة زاتكا مرسلة ومقبولة، مع PDF عربي وإنجليزي فيه رمز QR.

قبل ما تربط: زد تقول إن فواتير الشركات في زد وزد كاشير فيها متطلبات الهيئة ومنصة فاتورة، فتأكد من لوحة متجرك إذا كانت فواتيرك تنرسل للهيئة أصلاً، عشان ما تدفع مرتين. ماثل يفيدك إذا عندك نظام أو قناة بيع ثانية برّا زد، أو تبي جهازك وسلسلة فواتيرك تحت يدك.

الحدث اللي تستمع له

order.payment_status.update: 'Triggered when an order's payment status changes to paid or unpaid' (unpaid covers pending, refunded, voided). The payload uses the Order schema

التسجيل

Merchant API: POST https://api.zid.sa/v1/managers/webhooks with headers Authorization (partner token) and X-Manager-Token; body {event, target_url, original_id, conditions?, username?, password?}. conditions only work for order.create and order.status.update

التحقق إن الطلب جاي من Zid

HTTP Basic: if the webhook was created with username/password, Zid sends Authorization: Basic base64(username:password). No HMAC signature is documented

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

لو المبلغ شامل الضريبة (وهو الغالب)، أرسله زي ما هو مع "prices_include_vat": true.

الكود

يستقبل الحدث، يتحقق منه، ويستدعي matheel_invoice(items): الدالة الجاهزة اللي تقفل صف الجهاز وترسل الفاتورة وتحفظ المفتاح الجديد.

<?php
// Zid sends Basic auth built from the username/password you gave when creating the webhook.
$expected = 'Basic ' . base64_encode(getenv('ZID_HOOK_USER') . ':' . getenv('ZID_HOOK_PASS'));
if (!hash_equals($expected, $_SERVER['HTTP_AUTHORIZATION'] ?? '')) { http_response_code(401); exit; }
$o = json_decode(file_get_contents('php://input'), true);
http_response_code(200);
if (($o['payment_status'] ?? '') !== 'paid') exit;
$items = array_map(fn($p) => [
    'name'     => $p['name'],
    'quantity' => (string) $p['quantity'],
    // discounted_total includes VAT: remove it and divide by quantity.
    'price'    => number_format($p['discounted_total'] / $p['quantity'] / (1 + $p['tax_percentage']), 2, '.', ''),
], $o['products']);
matheel_invoice($items);

ملاحظات

Field names and their meanings come from the View Order API (the webhook page says its payload is the Order schema, but the schema did not render). Unknown: whether the order sits at the payload root or under a wrapper key, so log one real delivery first. payment_status values documented on View Order: pending, paid, failed, refunded. Some PHP hosts drop the Authorization header before it reaches $_SERVER. The webhook overview documents no signature or secret beyond Basic auth.

أسئلة شائعة

هل Zid يرسل الفواتير لزاتكا بنفسه؟

Zid متجر إلكتروني، وربطه مع الهيئة يكون عن طريق خدمة مثل ماثل: كل دفعة ناجحة تتحول لفاتورة مرسلة للهيئة.

لازم أعدّل الأسعار عشان الضريبة؟

لا. أرسل المبلغ اللي دفعه العميل مع "prices_include_vat": true، وماثل يطلّع الضريبة ويخلّي المبلغ المستحق في الفاتورة نفس المدفوع.

وش يصير لو جت دفعتين بنفس الثانية؟

فواتير الجهاز تمشي ورا بعض. اقفل صف الجهاز وقت الإرسال (موجود في الدالة الجاهزة)، وماثل يرفض أي نسخة قديمة من مفتاح الجهاز بـ 409 عشان السلسلة ما تنكسر.

المصادر الرسمية: docs.zid.sa/webhooks · docs.zid.sa/webhook-events-order.md · docs.zid.sa/create-a-webhook.md · docs.zid.sa/view-order-12479054e0.md

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

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

ابدأ الأسعار