ربط Salla مع زاتكا

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

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

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

سلة تصدر فاتورة ضريبية بنفسها عند اكتمال الطلب. تأكد إن فاتورتها مربوطة مع الهيئة في المرحلة الثانية قبل ما تضيف ماثل، عشان ما تصدر فاتورتين لنفس الطلب.

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

order.payment.updated ('triggered when an order payment has been updated'). Salla has no dedicated 'order paid' event; order.created and order.status.updated are the alternatives

التسجيل

Salla Partners portal > My Apps > your app > App Scope: Webhooks 'Read and Write' > Webhooks/Notifications section: add URL and Store Events. Merchant API alternative: Register Webhook endpoint (docs.salla.dev/webhooks/subscribe)

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

Signature strategy (default for Partner apps): headers X-Salla-Security-Strategy: Signature and X-Salla-Signature = hex HMAC-SHA256 of the request body with the webhook secret. Token strategy: the token itself in the Authorization header

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

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

الكود

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

<?php
// Salla webhook (Signature strategy): X-Salla-Signature = hex HMAC-SHA256 of the raw body.
$raw = file_get_contents('php://input');
$mine = hash_hmac('sha256', $raw, getenv('SALLA_WEBHOOK_SECRET'));
if (!hash_equals($mine, $_SERVER['HTTP_X_SALLA_SIGNATURE'] ?? '')) { http_response_code(401); exit; }
$e = json_decode($raw, true);
http_response_code(200);
$o = $e['data'];
// Skip orders still waiting for payment (e.g. bank transfer not confirmed yet).
if ($e['event'] !== 'order.payment.updated' || $o['is_pending_payment']) exit;
$items = array_map(fn($i) => [
    'name'     => $i['name'],
    'quantity' => (string) $i['quantity'],
    'price'    => number_format($i['amounts']['price_without_tax']['amount'], 2, '.', ''),
], $o['items']);
matheel_invoice($items);

ملاحظات

Unconfirmed: (1) whether order.payment.updated fires exactly once when payment is confirmed; (2) what is_pending_payment means (it appears in the sample payloads, but its schema tab did not render); (3) whether items[].amounts.price_without_tax is per unit or per line (every sample has quantity 1). Salla's own Node sample hashes JSON.stringify(req.body), which can differ from the raw bytes; its PHP sample hashes the raw body, as here. The docs call the hash 64 characters for Signature and 32 for Token; that is inconsistent. Salla also has an invoice.created event ('Tax Invoice' with a qr_code field, fired when the order is completed or restored), so check whether the store already issues ZATCA invoices through Salla before adding Matheel.

أسئلة شائعة

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

سلة تصدر فاتورة ضريبية بنفسها عند اكتمال الطلب. تأكد إن فاتورتها مربوطة مع الهيئة في المرحلة الثانية قبل ما تضيف ماثل، عشان ما تصدر فاتورتين لنفس الطلب.

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

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

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

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

المصادر الرسمية: docs.salla.dev/webhooks.md · docs.salla.dev/421119m0 · docs.salla.dev/webhook-events/orders.md · docs.salla.dev/webhook-events/invoice.md · docs.salla.dev/webhooks/subscribe.md

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

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

ابدأ الأسعار