ربط 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)
المبلغ والبنود
- المبلغ:
Sales Invoice: net_total, total_taxes_and_charges, grand_total, outstanding_amount; Sales Invoice Item: rate, net_rate, amount, net_amount - البنود:
items[].item_name, items[].qty (send with {{ doc["items"] | tojson }}) - إيميل العميل:
contact_email
لو المبلغ شامل الضريبة (وهو الغالب)، أرسله زي ما هو مع "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 عشان السلسلة ما تنكسر.