مرجع API

خطة الأعمال

ادمج CleverInvo في سير عملك. قم بإدارة العملاء وإنشاء الفواتير وتنزيل ملفات PDF برمجياً.

المصادقة

تتطلب جميع طلبات API رمز Bearer. أنشئ مفتاح API من لوحة التحكم، ثم قم بتضمينه في رأس Authorization.

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

العملاء

GET/api/v1/clients

عرض جميع العملاء النشطين. يدعم التصفح والبحث.

الاستجابة
{
  "data": [
    {
      "id": "clx...",
      "name": "Acme Corp",
      "email": "[email protected]",
      "address": "123 Main St, New York, NY 10001",
      "taxId": "US-123456789",
      "phone": "+1-555-0100",
      "notes": "Net 30 terms",
      "isActive": true,
      "createdAt": "2024-01-15T00:00:00.000Z",
      "updatedAt": "2024-01-15T00:00:00.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20,
  "totalPages": 1
}
POST/api/v1/clients

إنشاء عميل جديد. يخضع لحد العملاء في خطتك.

نص الطلب
{
  "name": "Acme Corp",
  "email": "[email protected]",
  "address": "123 Main St, New York, NY 10001",
  "taxId": "US-123456789",
  "phone": "+1-555-0100",
  "notes": "Net 30 terms"
}
الاستجابة
{
  "data": {
    "id": "clx...",
    "name": "Acme Corp",
    "email": "[email protected]",
    "address": "123 Main St, New York, NY 10001",
    "taxId": "US-123456789",
    "phone": "+1-555-0100",
    "notes": "Net 30 terms",
    "isActive": true,
    "createdAt": "2024-01-15T00:00:00.000Z",
    "updatedAt": "2024-01-15T00:00:00.000Z"
  }
}
GET/api/v1/clients/:id

الحصول على عميل واحد بواسطة المعرف.

الاستجابة
{
  "data": {
    "id": "clx...",
    "name": "Acme Corp",
    "email": "[email protected]",
    "address": "123 Main St, New York, NY 10001",
    "taxId": "US-123456789",
    "phone": "+1-555-0100",
    "notes": "Net 30 terms",
    "isActive": true,
    "createdAt": "2024-01-15T00:00:00.000Z",
    "updatedAt": "2024-01-15T00:00:00.000Z"
  }
}
PUT/api/v1/clients/:id

تحديث عميل. يمكن تعديل جميع الحقول.

نص الطلب
{
  "name": "Acme Corporation",
  "email": "[email protected]",
  "phone": "+1-555-0200"
}
الاستجابة
{
  "data": {
    "id": "clx...",
    "name": "Acme Corporation",
    "email": "[email protected]",
    "address": "123 Main St, New York, NY 10001",
    "taxId": "US-123456789",
    "phone": "+1-555-0200",
    "notes": "Net 30 terms",
    "isActive": true,
    "createdAt": "2024-01-15T00:00:00.000Z",
    "updatedAt": "2024-06-01T00:00:00.000Z"
  }
}
DELETE/api/v1/clients/:id

حذف ناعم لعميل. يضبط isActive على false. لا يمكن حذف العملاء الذين لديهم فواتير حالية بشكل نهائي.

الاستجابة
204 No Content

الفواتير

GET/api/v1/invoices

عرض الفواتير. يدعم التصفح والبحث والتصفية حسب clientId أو الحالة.

الاستجابة
{
  "data": [
    {
      "id": "clx...",
      "clientId": "clx...",
      "invoiceNumber": "INV-0001",
      "currency": "USD",
      "issueDate": "2024-06-01",
      "dueDate": "2024-07-01",
      "subtotal": 5000.00,
      "taxTotal": 500.00,
      "discountTotal": 0,
      "total": 5500.00,
      "status": "SENT",
      "createdAt": "2024-06-01T00:00:00.000Z",
      "client": {
        "name": "Acme Corp",
        "email": "[email protected]"
      }
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20,
  "totalPages": 1
}
POST/api/v1/invoices

إنشاء فاتورة وتوليد PDF تلقائياً. يخضع لحدود الخطة.

نص الطلب
{
  "clientId": "clx...",
  "invoiceNumber": "INV-0042",
  "currency": "USD",
  "issueDate": "2024-06-01",
  "dueDate": "2024-07-01",
  "lineItems": [
    {
      "description": "Web Development",
      "quantity": 40,
      "unitPrice": 125.00,
      "taxRate": 10
    }
  ],
  "notes": "Thank you for your business",
  "terms": "Payment due within 30 days"
}
الاستجابة
{
  "data": {
    "id": "clx...",
    "invoiceNumber": "INV-0042",
    "total": 5500.00,
    "status": "DRAFT"
  }
}
GET/api/v1/invoices/:id

الحصول على تفاصيل الفاتورة الكاملة بما في ذلك البنود ومعلومات العميل.

الاستجابة
{
  "data": {
    "id": "clx...",
    "clientId": "clx...",
    "invoiceNumber": "INV-0042",
    "currency": "USD",
    "issueDate": "2024-06-01",
    "dueDate": "2024-07-01",
    "lineItems": [
      {
        "description": "Web Development",
        "quantity": 40,
        "unitPrice": 125.00,
        "amount": 5000.00,
        "taxRate": 10
      }
    ],
    "subtotal": 5000.00,
    "taxTotal": 500.00,
    "discountTotal": 0,
    "total": 5500.00,
    "status": "SENT",
    "notes": "Thank you for your business",
    "terms": "Payment due within 30 days",
    "sentViaEmail": true,
    "sentAt": "2024-06-01T12:00:00.000Z",
    "paidAt": null,
    "createdAt": "2024-06-01T00:00:00.000Z",
    "client": {
      "name": "Acme Corp",
      "email": "[email protected]"
    }
  }
}
PUT/api/v1/invoices/:id

تحديث فاتورة. يمكن تعديل الفواتير المسودة فقط.

نص الطلب
{
  "dueDate": "2024-07-15",
  "lineItems": [
    {
      "description": "Web Development",
      "quantity": 50,
      "unitPrice": 125.00,
      "taxRate": 10
    }
  ],
  "notes": "Updated scope"
}
الاستجابة
{
  "data": {
    "id": "clx...",
    "invoiceNumber": "INV-0042",
    "total": 6875.00,
    "status": "DRAFT"
  }
}
DELETE/api/v1/invoices/:id

حذف الفاتورة وملف PDF المُنشأ بشكل دائم.

الاستجابة
204 No Content
GET/api/v1/invoices/:id/pdf

تنزيل الفاتورة كملف PDF. يُرجع PDF ثنائي مع رأس Content-Disposition.

الاستجابة
Content-Type: application/pdf
Content-Disposition: attachment; filename="INV-0042.pdf"

<binary PDF data>

التصفح

تقبل نقاط نهاية القائمة معاملات الاستعلام التالية:

المعاملالافتراضيالوصف
page1رقم الصفحة (الحد الأدنى: 1)
limit20العناصر لكل صفحة (1–100)
search—التصفية بالاسم أو البريد الإلكتروني أو رقم الفاتورة (بحد أقصى 255 حرفاً)
clientId—تصفية الفواتير حسب العميل (الفواتير فقط)
status—التصفية حسب الحالة: DRAFT، SENT، VIEWED، PAID، PARTIALLY_PAID، OVERDUE
GET /api/v1/clients?page=2&limit=10&search=acme

الأخطاء

تُرجع API رموز حالة HTTP القياسية. تتضمن استجابات الخطأ نص JSON مع حقل error.

الحالةالوصف
400Bad Request — معاملات غير صالحة أو حقول مطلوبة مفقودة
401Unauthorized — مفتاح API غير صالح أو مفقود
403Forbidden — تم الوصول إلى حد الخطة (العملاء أو الفواتير أو الميزة)
404Not Found — المورد غير موجود أو غير قابل للوصول
429Too Many Requests — تم تجاوز حد المعدل
500Internal Server Error — فشل غير متوقع، حاول مرة أخرى لاحقاً
{
  "error": "Missing required field: name"
}

حدود المعدل

طلبات API محدودة بـ 120 طلباً في الدقيقة لكل مفتاح API.

عند تجاوز الحد، تُرجع الطلبات 429 Too Many Requests. انتظر قبل إعادة المحاولة.