دليل الربط الكامل مع واجهة يسر بلس API

1. إنشاء المفتاح والمصادقة

من داخل حساب المنشأة افتح الإعدادات ← الربط عبر API، اكتب اسمًا واضحًا للتكامل ثم اضغط «إنشاء مفتاح API». سيظهر المفتاح مرة واحدة فقط.

Authorization: Bearer dft_live_xxxxxxxxxxxxxxxxxxxx

العنوان الأساسي لكل الطلبات:

https://yusrplus.com/api/public/v1

2. نقاط الربط المتاحة

تدعم قوائم البيانات limit من 1 إلى 100 و offset للصفحات. مثال: ?limit=50&offset=100.

const response = await fetch(
  "https://yusrplus.com/api/public/v1/invoices?limit=50",
  { headers: { Authorization: `Bearer ${process.env.DAFTORA_API_KEY}` } }
);
if (!response.ok) throw new Error(await response.text());
const { data, meta } = await response.json();

3. إضافة العملاء تلقائيًا

يمكنك إرسال code من نظامك ليظل مرجع العميل ثابتًا بين النظامين. يجب أن يكون الكود فريدًا داخل المنشأة.

curl -X POST https://yusrplus.com/api/public/v1/customers \
  -H "Authorization: Bearer $DAFTORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "WEB-1001",
    "name": "شركة المثال",
    "email": "finance@example.com",
    "phone": "+201000000000"
  }'

4. إنشاء الفواتير وترحيلها

استخدم customerId أو customerCode. عند إنشاء الفاتورة يُنشئ يسر بلس القيد المحاسبي المتوازن تلقائيًا. حالات الفاتورة المدعومة: draft و sent و partially_paid و paid و overdue و cancelled.

curl -X POST https://yusrplus.com/api/public/v1/invoices \
  -H "Authorization: Bearer $DAFTORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customerCode": "WEB-1001",
    "number": "STORE-INV-9001",
    "totalMinor": 125000,
    "paidMinor": 0,
    "status": "sent",
    "issueDate": "2026-09-09",
    "dueDate": "2026-09-23"
  }'

5. المنتجات والمخزون

إضافة المنتج تحدّث شاشة المخزون وقيمته فورًا. salePriceMinor بالقروش، بينما stockQuantity و reorderLevel أعداد صحيحة.

curl -X POST https://yusrplus.com/api/public/v1/products \
  -H "Authorization: Bearer $DAFTORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sku": "SKU-500",
    "name": "منتج تجريبي",
    "salePriceMinor": 49900,
    "stockQuantity": 25,
    "reorderLevel": 5
  }'

6. الحسابات والقيود اليومية

GET /accounts يعرض إجمالي المدين والدائن والرصيد لكل كود حساب. ويمكن استيراد قيد يدوي من نظام خارجي بشرط تساوي إجمالي المدين والدائن.

curl -X POST https://yusrplus.com/api/public/v1/journal-entries \
  -H "Authorization: Bearer $DAFTORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "ERP-ENTRY-1007",
    "postingDate": "2026-09-09",
    "lines": [
      {"accountCode":"1100-CASH","debitMinor":50000,"creditMinor":0},
      {"accountCode":"4100-SALES","debitMinor":0,"creditMinor":50000}
    ]
  }'

7. الأخطاء والتشغيل الآمن

تستخدم الواجهة أكواد HTTP القياسية: 201 للإنشاء، 401 لمفتاح غير صالح أو صلاحية ناقصة، 404 لمرجع غير موجود، 409 للتكرار، و422 لخطأ التحقق.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "totalMinor must be a positive integer"
  }
}

• ضع المفتاح في متغير بيئة على الخادم.
• استخدم رقم فاتورة أو reference فريدًا لتجنب التكرار عند إعادة المحاولة.
• أوقف المفتاح فورًا من الإعدادات إذا اشتبهت في تسريبه.
• سجّل كود الاستجابة ونص الخطأ، ولا تسجّل المفتاح نفسه.