كل المستندات

البدء

نفّذ أول طلب لواجهة نيزا وتأكد من أن الدمج يعمل.

البدء

هذا الدليل يساعدك على تنفيذ أول استدعاء API والتحقق من التكامل.

المتطلبات

  • حساب نيزا باشتراك فعّال
  • مفتاح API (راجع قسم المصادقة في مرجع API)
  • معرفة أساسية بواجهات REST وJSON

الخطوة 1: احصل على مفتاح API

  1. سجّل الدخول إلى لوحة تحكم نيزا
  2. انتقل إلى SettingsAPI Keys
  3. انقر Create API Key
  4. انسخ المفتاح واحفظه بأمان (الصيغة: naiza_api_sk_live_...)

الخطوة 2: نفّذ أول استدعاء

قيّم معاملة للحصول على قرار عبر POST /api/v1/decisions/evaluate.

cURL
curl -X POST https://api.naiza.ai/api/v1/decisions/evaluate \
  -H "x-api-key: naiza_api_sk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "eventName": "payment.attempt",
    "customer": {
      "externalId": "cust_test_123",
      "email": "test@example.com"
    },
    "ip": "203.0.113.42"
  }'

الخطوة 3: افهم الاستجابة

تبدو الاستجابة الناجحة بهذا الشكل:

Decision response
{
  "decision": "ALLOW",
  "riskScore": 25,
  "riskLevel": "low",
  "reasonCodes": [
    {
      "code": "NO_RISK_INDICATORS",
      "explanation": "No risk indicators detected"
    }
  ],
  "correlationIds": {
    "requestId": "req_abc123xyz",
    "eventId": "evt_ckm9876543210",
    "customerId": "cus_test_123"
  },
  "ruleVersion": {
    "version": "v1.0.0"
  },
  "evaluatedAt": "2025-01-15T14:30:00.000Z"
}

الحقول الأساسية:

  • decision: ALLOW أو BLOCK أو REVIEW
  • riskScore: من 0 إلى 100 (الأعلى = أكثر خطورة)
  • riskLevel: low أو medium أو high أو critical
  • correlationIds.eventId: استخدمه لاحقًا لاستعلام تفاصيل القرار

الخطوة 4: تحقق من توقيع Webhook (اختياري)

إذا هيّأت Webhooks، تحقق من التوقيع باستخدام HMAC-SHA256 وترويسة x-webhook-signature.

Node.js
const crypto = require("crypto");

function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(JSON.stringify(payload))
    .digest("hex");

  const provided = signature.replace("sha256=", "");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(provided));
}

الخطوة 5: استعلم عن قرار

استخدم eventId من correlationIds لاستعلام تفاصيل القرار:

GET /api/v1/decisions/:eventId
curl -X GET "https://api.naiza.ai/api/v1/decisions/evt_ckm9876543210" \
  -H "x-api-key: naiza_api_sk_live_YOUR_KEY_HERE"

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

  • اقرأ دليل البدء السريع للعمليات الشائعة
  • راجع أمثلة التكامل لأنماط الكود
  • استكشف مرجع API للتوثيق الكامل

استكشاف الأخطاء

خطأ "Invalid API key"

  • تحقق من صيغة المفتاح: naiza_api_sk_live_<32-chars>
  • تأكد من عدم وجود مسافات أو أسطر زائدة
  • تأكد أن المفتاح لم يُلغَ

خطأ "Validation failed"

  • راجع الحقول المطلوبة في توثيق API
  • تحقق من أنواع الحقول وصيغها
  • تأكد أن JSON منسّق بشكل صحيح