ربط Shopify مع زاتكا

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

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

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

orders/paid (GraphQL enum ORDERS_PAID): 'Occurs whenever an order is paid.' Needs read_orders scope

التسجيل

App config shopify.app.toml: [[webhooks.subscriptions]] topics = ["orders/paid"], uri = "https://your-app.example.com/webhooks/orders-paid" (under [webhooks] api_version), then deploy the app

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

Header X-Shopify-Hmac-SHA256 = base64 HMAC-SHA256 of the raw request body, keyed with the app's client secret; compare with timingSafeEqual

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

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

الكود

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

import express from "express";
import crypto from "node:crypto";
const app = express();
// Shopify signs the raw body, so keep it as a Buffer.
app.post("/webhooks/orders-paid", express.raw({ type: "*/*" }), async (req, res) => {
  const hmac = Buffer.from(req.get("X-Shopify-Hmac-Sha256") || "", "base64");
  const mine = crypto.createHmac("sha256", process.env.SHOPIFY_CLIENT_SECRET).update(req.body).digest();
  if (hmac.length !== mine.length || !crypto.timingSafeEqual(hmac, mine)) return res.sendStatus(401);
  res.sendStatus(200); // answer fast, then file
  const order = JSON.parse(req.body.toString("utf8"));
  const items = order.line_items.map((li) => {
    const discount = li.discount_allocations.reduce((s, d) => s + Number(d.amount), 0);
    const unit = Number(li.price) - discount / li.quantity;
    const net = order.taxes_included ? unit / 1.15 : unit; // price must be before VAT
    return { name: li.name, quantity: String(li.quantity), price: net.toFixed(2) };
  });
  await matheel_invoice(items);
});
app.listen(3000);

ملاحظات

taxes_included is in the orders/paid sample payload, but the pages read did not define it in words; the code assumes true means line prices include VAT. Shopify recommends discount_allocations over line_items[].total_discount, which is only set for draft orders, scripts or the API. Shipping is in shipping_lines, not line_items. The 1.15 divisor assumes 15% VAT on every line. Shopify's own example compares base64 strings with timingSafeEqual; the sketch compares the decoded bytes and checks the length first, because timingSafeEqual throws on unequal lengths.

أسئلة شائعة

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

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

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

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

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

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

المصادر الرسمية: shopify.dev/docs/api/admin-graphql/latest/enums/WebhookSubsc · shopify.dev/docs/api/webhooks/latest?reference=toml · shopify.dev/docs/apps/build/webhooks/subscribe · shopify.dev/docs/apps/build/webhooks/subscribe/https · shopify.dev/docs/api/admin-rest/latest/resources/order

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

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

ابدأ الأسعار