ربط 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
المبلغ والبنود
- المبلغ:
total_price, total_tax, current_total_price; line_items[].price (unit price before discounts, shop currency), line_items[].discount_allocations[].amount - البنود:
line_items[].name (variant name) / line_items[].title (product title), line_items[].quantity - إيميل العميل:
email (also contact_email)
لو المبلغ شامل الضريبة (وهو الغالب)، أرسله زي ما هو مع "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 عشان السلسلة ما تنكسر.