ربط ERPNext / Frappe مع زاتكا

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

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

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

Frappe Webhook on DocType 'Sales Invoice', Doc Event on_submit (other events: after_insert, on_update, on_cancel, on_trash, on_update_after_submit, on_change, workflow_transition), with an optional condition

التسجيل

Integrations > Webhook > Webhook: DocType, Doc Event, Conditions, Request URL, Request Method POST, Request Structure JSON (Jinja), Enable Security + Webhook Secret

التحقق إن الطلب جاي من ERPNext / Frappe

Header X-Frappe-Webhook-Signature = base64 HMAC-SHA256 of the JSON body, keyed with the Webhook Secret (frappe/integrations/doctype/webhook/webhook.py signs frappe.as_json(data), the same bytes it sends)

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

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

الكود

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

import base64, hashlib, hmac, os
from flask import Flask, request, abort

app = Flask(__name__)

# Request Structure (JSON):
# {"name": "{{ doc.name }}", "outstanding_amount": {{ doc.outstanding_amount }}, "items": {{ doc["items"] | tojson }}}
@app.post("/erpnext/sales-invoice")
def sales_invoice():
    mac = hmac.new(os.environ["FRAPPE_WEBHOOK_SECRET"].encode(), request.get_data(), hashlib.sha256)
    if not hmac.compare_digest(base64.b64encode(mac.digest()).decode(),
                               request.headers.get("X-Frappe-Webhook-Signature", "")):
        abort(401)
    inv = request.get_json()
    if inv["outstanding_amount"] > 0:
        return "", 200  # not paid in full at submit
    items = [{"name": i["item_name"], "quantity": str(i["qty"]), "price": f'{i["net_rate"]:.2f}'}
             for i in inv["items"]]
    matheel_invoice(items)
    return "", 200

ملاحظات

on_submit catches invoices paid at submit (POS, 'Include Payment'). Unknown: whether a later Payment Entry that sets the invoice status to Paid triggers a Sales Invoice webhook; if not, hook Payment Entry on_submit and read its references. That net_rate is the unit rate after discounts without tax is inferred from the field label 'Net Rate', not from a doc. The Frappe guide shows only on_update as an example; the event list comes from webhook.json. Sales Invoice status options include Paid, Partly Paid and Unpaid.

أسئلة شائعة

هل ERPNext / Frappe يرسل الفواتير لزاتكا بنفسه؟

ERPNext / Frappe نظام ERP، وربطه مع الهيئة يكون عن طريق خدمة مثل ماثل: كل دفعة ناجحة تتحول لفاتورة مرسلة للهيئة.

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

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

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

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

المصادر الرسمية: docs.frappe.io/framework/user/en/guides/integration/webhooks · github.com/frappe/frappe/blob/develop/frappe/integrations/do · github.com/frappe/frappe/blob/develop/frappe/integrations/do · github.com/frappe/erpnext/blob/develop/erpnext/accounts/doct · github.com/frappe/erpnext/blob/develop/erpnext/accounts/doct

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

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

ابدأ الأسعار