كيفية أتمتة الفوترة باستخدام واجهة برمجة تطبيقات CleverInvo

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

واجهة برمجة تطبيقات CleverInvo تجعل كل هذا ممكناً. يغطي هذا الدليل الأساسيات: المصادقة وإنشاء العملاء وتوليد الفواتير وإعداد Webhooks.

---

المتطلبات المسبقة

واجهة برمجة التطبيقات متاحة في خطة Business. تحتاج:

1. حساب CleverInvo على خطة Business
2. مفتاح API (أنشئه من لوحة التحكم > مفاتيح API)
3. معرفة أساسية بـ REST APIs و JSON

جميع طلبات API تستخدم HTTPS وتعيد استجابات JSON. الرابط الأساسي:

https://cleverinvo.com/api/v1

المصادقة

ضمّن مفتاح API في رأس Authorization:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://cleverinvo.com/api/v1/clients

---

إدارة العملاء

قبل إنشاء فاتورة، تحتاج عميلاً في النظام.

إنشاء عميل

curl -X POST https://cleverinvo.com/api/v1/clients \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "شركة أكمي",
    "email": "[email protected]",
    "address": "شارع الأعمال 123، الرياض",
    "taxId": "300000000000003",
    "phone": "+966-11-123-4567"
  }'

قائمة العملاء

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://cleverinvo.com/api/v1/clients?page=1&limit=20"

---

إنشاء الفواتير

هنا تتألق القيمة الحقيقية لواجهة برمجة التطبيقات. يمكنك إنشاء فواتير مهنية ومرقمة باستدعاء API واحد.

إنشاء فاتورة

curl -X POST https://cleverinvo.com/api/v1/invoices \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "cli_abc123def456",
    "currency": "SAR",
    "issueDate": "2026-03-01",
    "dueDate": "2026-03-31",
    "lineItems": [
      {
        "description": "إعادة تصميم الموقع - المرحلة 1",
        "quantity": 1,
        "unitPrice": 20000.00
      },
      {
        "description": "تطوير الواجهة الأمامية",
        "quantity": 40,
        "unitPrice": 500.00
      }
    ],
    "notes": "شكراً لتعاملكم.",
    "terms": "الدفع خلال 30 يوماً. فائدة 1.5% شهرياً على المدفوعات المتأخرة."
  }'

النظام تلقائياً:

• يعين رقم الفاتورة التسلسلي التالي
• يحسب إجماليات البنود والمجموع الفرعي والإجمالي
• يولّد PDF ويعيد الرابط
• يضع الحالة على DRAFT

فاتورة مع ضريبة

لتضمين الضريبة، أضف taxRate لكل بند:

{
  "lineItems": [
    {
      "description": "خدمات استشارية",
      "quantity": 20,
      "unitPrice": 800.00,
      "taxRate": 15
    }
  ]
}

---

إدارة حالة الفاتورة

الفواتير تمر بدورة حياة: DRAFT (مسودة)، SENT (مرسلة)، VIEWED (مُعاينة)، PAID (مدفوعة)، PARTIALLY_PAID (مدفوعة جزئياً)، OVERDUE (متأخرة).

# وسم كمرسلة
curl -X PATCH https://cleverinvo.com/api/v1/invoices/inv_xyz789ghi012 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "SENT"}'

# وسم كمدفوعة
curl -X PATCH https://cleverinvo.com/api/v1/invoices/inv_xyz789ghi012 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "PAID"}'

---

أنماط التكامل الشائعة

النمط 1: من CRM إلى فاتورة

async function onDealClosed(deal) {
  let client = await cleverinvo.clients.findByEmail(deal.customerEmail);
  if (!client) {
    client = await cleverinvo.clients.create({
      name: deal.customerName,
      email: deal.customerEmail,
    });
  }

  await cleverinvo.invoices.create({
    clientId: client.id,
    currency: deal.currency,
    issueDate: new Date().toISOString().split("T")[0],
    dueDate: addDays(new Date(), 30).toISOString().split("T")[0],
    lineItems: deal.products.map((p) => ({
      description: p.name,
      quantity: p.quantity,
      unitPrice: p.price,
    })),
  });
}

النمط 2: فوترة الاشتراك الشهري

async function generateMonthlyInvoices() {
  const clients = await cleverinvo.clients.list({ isActive: true });

  for (const client of clients.data) {
    if (client.retainerAmount) {
      await cleverinvo.invoices.create({
        clientId: client.id,
        currency: "SAR",
        lineItems: [
          {
            description: `اشتراك شهري - ${format(today, "MMMM yyyy")}`,
            quantity: 1,
            unitPrice: client.retainerAmount,
          },
        ],
      });
    }
  }
}

---

حدود المعدل

الخطة	الحد
Business	100 طلب في الدقيقة

عند تجاوز الحد، تعيد API 429 Too Many Requests.

---

معالجة الأخطاء

الكود	حالة HTTP	المعنى
UNAUTHORIZED	401	مفتاح API غير صالح أو مفقود
FORBIDDEN	403	وصول API غير متاح في خطتك
NOT_FOUND	404	المورد غير موجود
VALIDATION_ERROR	422	بيانات الطلب غير صالحة
RATE_LIMITED	429	طلبات كثيرة جداً
INTERNAL_ERROR	500	خطأ في الخادم (تواصل مع الدعم)

---

الخطوات التالية

واجهة برمجة تطبيقات CleverInvo مصممة لتتكامل مع سير عملك الحالي. ابدأ بحالة استخدام واحدة، اجعلها تعمل، ثم توسع.

التوثيق الكامل لواجهة برمجة التطبيقات متاح في /docs/api.

احصل على مفتاح API الخاص بك ->