اربط نظامك برودكس

واجهة برمجية بسيطة لربط متجرك أو تطبيقك أو نظام التوصيل أو أي نظام داخلي بالمحاسبة والفوترة الإلكترونية في رودكس.

المصادقة

كل شركة على رودكس لها نظام مستقل برابط خاص، مثل https://mycompany.rowdx.com. من داخل النظام: الإعدادات ← المطورون (API) أنشئ مفتاحًا، واختر صلاحيته (قراءة فقط، أو قراءة وكتابة). السر يظهر مرة واحدة.

Authorization: token <api_key>:<api_secret>

احفظ السر في الخادم عندك فقط، ولا تضعه في تطبيق جوال أو صفحة ويب يراها العميل. ويمكنك إلغاء أي مفتاح في أي وقت من نفس الصفحة.

أول طلب

كل نقاط الوصول بالشكل: https://<company>.rowdx.com/api/method/rowdx.v1.<resource>.<action>، والرد JSON داخل المفتاح message.

curl https://mycompany.rowdx.com/api/method/rowdx.v1.me \
  -H "Authorization: token KEY:SECRET"

{"message": {"company": "شركة الأفق", "currency": "SAR", "country": "Saudi Arabia", "scope": "write", "version": "1"}}

نقاط الوصول

طلبات GET بباراميترات في الرابط، وطلبات POST بجسم JSON (أو form). القوائم ترجع {"data": [...], "limit", "offset"}.

إنشاء فاتورة

أرسل الأصناف بالكود (SKU) أو بالاسم، والعميل بالمعرّف أو بالاسم (يُنشأ تلقائيًا لو غير موجود). reference رقم الطلب عندك، ويمنع إنشاء نفس الفاتورة مرتين. الضريبة تُحسب من قالب الضريبة الافتراضي للشركة.

curl -X POST https://mycompany.rowdx.com/api/method/rowdx.v1.invoices.create \
  -H "Authorization: token KEY:SECRET" -H "Content-Type: application/json" \
  -d '{
    "customer_name": "مؤسسة الأفق التجارية",
    "reference": "ORDER-10045",
    "items": [
      {"code": "COF-250", "qty": 2, "rate": 35},
      {"name": "خدمة توصيل", "qty": 1, "rate": 15, "service": 1}
    ],
    "taxes_included": 0,
    "paid": 1,
    "mode_of_payment": "Cash"
  }'

الرد: الفاتورة بالأصناف والإجماليات وحالة الفوترة الإلكترونية (einvoice.status). ولرابط PDF للعميل: rowdx.v1.invoices.link?id=...

الفاتورة المعتمدة والمبلّغة للجهة الضريبية لا تُلغى؛ لتصحيحها أصدر إشعارًا دائنًا من النظام.

Webhooks

سجّل رابطًا (https) لحدث، وسيصلك طلب POST بجسم JSON عند وقوعه. لو أرسلت secret، يُوقَّع الجسم بـ HMAC-SHA256 (base64) في الترويسة X-Frappe-Webhook-Signature.

الأحداث: invoice.submitted invoice.cancelled payment.created customer.created customer.updated item.created item.updated

curl -X POST https://mycompany.rowdx.com/api/method/rowdx.v1.webhooks.create \
  -H "Authorization: token KEY:SECRET" -H "Content-Type: application/json" \
  -d '{"event": "invoice.submitted", "url": "https://example.com/rowdx", "secret": "my-secret"}'

// ما يصلك:
{"event": "invoice.submitted", "data": {"id": "ACC-SINV-2026-00042", "date": "2026-10-23",
 "customer": "مؤسسة الأفق", "currency": "SAR", "net": 85.0, "tax": 12.75, "total": 97.75, "outstanding": 0, "reference": "ORDER-10045"}}

الأخطاء والحدود

JavaScript (Node.js)

const BASE = "https://mycompany.rowdx.com/api/method/rowdx.v1.";
const H = { Authorization: `token ${process.env.ROWDX_KEY}:${process.env.ROWDX_SECRET}`, "Content-Type": "application/json" };

const r = await fetch(BASE + "invoices.create", { method: "POST", headers: H, body: JSON.stringify({
  customer_name: "محمد أحمد", reference: "ORDER-1", items: [{ code: "COF-250", qty: 1, rate: 35 }], paid: 1 }) });
const { message: invoice } = await r.json();
console.log(invoice.id, invoice.total);

Python

import os, requests

BASE = "https://mycompany.rowdx.com/api/method/rowdx.v1."
H = {"Authorization": f"token {os.environ['ROWDX_KEY']}:{os.environ['ROWDX_SECRET']}"}

items = requests.get(BASE + "items.list", headers=H, params={"limit": 100}).json()["message"]["data"]
for it in items:
    print(it["code"], it["name"], it["price"])