البدء
هذا الدليل يساعدك على تنفيذ أول استدعاء API والتحقق من التكامل.
المتطلبات
- حساب نيزا باشتراك فعّال
- مفتاح API (راجع قسم المصادقة في مرجع API)
- معرفة أساسية بواجهات REST وJSON
الخطوة 1: احصل على مفتاح API
- سجّل الدخول إلى لوحة تحكم نيزا
- انتقل إلى Settings → API Keys
- انقر Create API Key
- انسخ المفتاح واحفظه بأمان (الصيغة:
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أوREVIEWriskScore: من 0 إلى 100 (الأعلى = أكثر خطورة)riskLevel:lowأوmediumأوhighأوcriticalcorrelationIds.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 منسّق بشكل صحيح