وثائق API

مقدمة

واجهة برمجة التطبيقات (API) لنظام NASEY CRM تتيح لك الوصول البرمجي لجميع بيانات ووظائف النظام. يمكنك استخدام API لبناء تطبيقات مخصصة، ربط أنظمة خارجية، أو أتمتة العمليات.

المتطلبات الأساسية

• حساب نشط في NASEY CRM
• خطة اشتراك تدعم API (احترافية أو أعلى)
• API Key صحيح ونشط
• معرفة أساسية بـ HTTP و JSON

نسخة API

النسخة الحالية هي v1. جميع المسارات تبدأ بـ /v1/. نحن نحتفظ بالتوافق مع النسخ السابقة قدر الإمكان، وسنشعرك مسبقاً بأي تغييرات كبيرة.

المصادقة

تستخدم NASEY CRM API مفاتيح API للمصادقة. يجب تضمين مفتاح API في header لكل طلب.

الحصول على API Key

1. سجل دخولك إلى لوحة تحكم NASEY CRM
2. اذهب إلى الإعدادات ← API و Integrations
3. انقر على "إنشاء مفتاح جديد"
4. اختر الصلاحيات المطلوبة
5. احفظ المفتاح في مكان آمن

كيفية استخدام المفتاح

أضف مفتاح API إلى header في كل طلب:

Authorization: Bearer YOUR_API_KEY_HERE
Content-Type: application/json
Accept: application/json

مثال بـ cURL

curl -X GET "https://api.nasey.com/v1/customers" \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json"

حدود الاستخدام

لضمان استقرار الخدمة للجميع، نطبق حدود على عدد الطلبات التي يمكن إرسالها.

Headers الاستجابة

كل استجابة تحتوي على معلومات حول حالة حدود الاستخدام:

التعامل مع تجاوز الحد

عند تجاوز الحد، ستحصل على:

• HTTP Status: 429 Too Many Requests
• Retry-After header: يحدد متى يمكن المحاولة مرة أخرى
• رسالة خطأ: توضح سبب الرفض

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

endpoints لإدارة بيانات العملاء في النظام.

curl -X GET "https://api.nasey.com/v1/customers?page=1&limit=10&search=أحمد" \
  -H "Authorization: Bearer YOUR_API_KEY_HERE"

{
  "success": true,
  "data": [
    {
      "id": 123,
      "name": "أحمد محمد السعيد",
      "email": "ahmed@example.com",
      "phone": "+966501234567",
      "company": "شركة التقنيات المتطورة",
      "status": "active",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-20T14:22:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 5,
    "total_items": 47,
    "per_page": 10
  }
}

curl -X POST "https://api.nasey.com/v1/customers" \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "فاطمة أحمد الزهراني",
    "email": "fatima@techcompany.com",
    "phone": "+966501234567",
    "company": "شركة التكنولوجيا الحديثة",
    "address": {
      "street": "طريق الملك عبدالعزيز",
      "city": "الرياض",
      "country": "SA"
    }
  }'

curl -X PUT "https://api.nasey.com/v1/customers/123" \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+966502345678",
    "company": "الشركة المطورة للتقنيات"
  }'

الفواتير

endpoints لإدارة الفواتير والمدفوعات.

{
  "success": true,
  "data": [
    {
      "id": 1001,
      "number": "INV-2024-001",
      "customer_id": 123,
      "customer_name": "أحمد محمد السعيد",
      "amount": 5250.00,
      "tax": 787.50,
      "total": 6037.50,
      "currency": "SAR",
      "status": "paid",
      "due_date": "2024-02-15",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

إدارة المشاريع

endpoints لإدارة المشاريع والمهام.

Webhooks

Webhooks تتيح لك تلقي إشعارات فورية عند حدوث أحداث معينة في النظام.

الأحداث المدعومة

إعداد Webhook

curl -X POST "https://api.nasey.com/v1/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/nasey",
    "events": ["invoice.paid", "customer.created"],
    "secret": "your_webhook_secret"
  }'

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

نظام NASEY CRM API يستخدم أكواد HTTP القياسية مع رسائل خطأ واضحة.

تنسيق رسائل الخطأ

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "البيانات المرسلة غير صحيحة",
    "details": {
      "email": ["البريد الإلكتروني مطلوب"],
      "name": ["الاسم يجب أن يكون أكثر من 3 أحرف"]
    }
  }
}

SDKs ومكتبات البرمجة

نوفر مكتبات جاهزة لتسهيل التكامل مع API في لغات البرمجة المختلفة.

npm install nasey-crm-sdk

const NASEY = require('nasey-crm-sdk');

const client = new NASEY({
  apiKey: 'YOUR_API_KEY_HERE'
});

// إنشاء عميل جديد
const customer = await client.customers.create({
  name: 'أحمد محمد',
  email: 'ahmed@example.com'
});

pip install nasey-crm

from nasey_crm import Client

client = Client(api_key='YOUR_API_KEY_HERE')

# إنشاء عميل جديد
customer = client.customers.create({
    'name': 'أحمد محمد',
    'email': 'ahmed@example.com'
})

composer require nasey/crm-sdk

use Nasey\CRM\Client;

$client = new Client('YOUR_API_KEY_HERE');

// إنشاء عميل جديد
$customer = $client->customers()->create([
    'name' => 'أحمد محمد',
    'email' => 'ahmed@example.com'
]);

gem install nasey-crm

require 'nasey/crm'

client = Nasey::CRM::Client.new(
  api_key: 'YOUR_API_KEY_HERE'
)

# إنشاء عميل جديد
customer = client.customers.create({
  name: 'أحمد محمد',
  email: 'ahmed@example.com'
})