كل المستندات

بداية سريعة

بداية سريعة مع واجهة نيزا: أرسل الأحداث، واقرأ القرارات، وأدر قوائم السماح والحظر، وسجّل نتائج التحقيق في خطوات قصيرة.

البدء السريع

أكثر العمليات استخدامًا مع واجهة نيزا.

1. تقييم معاملة

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

Node.js
const response = await fetch("https://api.naiza.ai/api/v1/decisions/evaluate", {
  method: "POST",
  headers: {
    "x-api-key": process.env.NAIZA_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    eventName: "payment.attempt",
    customer: {
      externalId: "cust_123",
      email: "user@example.com",
    },
    device: {
      fingerprint: "fp_abc123",
    },
    ip: "203.0.113.42",
    metadata: {
      amount: 99.99,
      currency: "USD",
    },
  }),
});

const decision = await response.json();

if (decision.decision === "deny") {
  console.log("Transaction blocked:", decision.reasonCodes);
} else if (decision.decision === "review") {
  console.log("Requires review:", decision.riskLevel);
} else {
  console.log("Transaction allowed");
}

2. الاستعلام عن قرار

استرجع تفاصيل قرار محدد باستخدام correlationIds.eventId.

GET /api/v1/decisions/:id
const decisionId = "evt_ckm9876543210";

const response = await fetch(
  `https://api.naiza.ai/api/v1/decisions/${decisionId}`,
  {
    headers: {
      "x-api-key": process.env.NAIZA_API_KEY,
    },
  },
);

const details = await response.json();
console.log("Decision details:", details);
console.log("Rules evaluated:", details.outputs.rulesEvaluated);
console.log("Reason codes:", details.reasonCodes);

2ب. إرسال حدث (غير متزامن)

استخدم الإرسال غير المتزامن إذا أردت أن يُستلم الحدث فورًا وتصلك نتيجة المعالجة لاحقًا عبر Webhooks:

POST /api/v1/events/async
const response = await fetch("https://api.naiza.ai/api/v1/events/async", {
  method: "POST",
  headers: {
    "x-api-key": process.env.NAIZA_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    eventName: "user.register",
    eventCategory: "AUTHENTICATION",
    customer: { externalId: "user_345678", email: "newuser@example.com" },
    ip: "10.0.0.25",
  }),
});

const accepted = await response.json();
console.log("Queued job:", accepted.jobId);

3. إضافة عنصر إلى قائمة الحظر

أضف عنوان IP إلى قائمة الحظر.

POST /api/v1/lists/ip
const response = await fetch("https://api.naiza.ai/api/v1/lists/ip", {
  method: "POST",
  headers: {
    "x-api-key": process.env.NAIZA_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    ip: "203.0.113.50",
    reason: "Known malicious IP from threat intelligence",
  }),
});

const entry = await response.json();
console.log("Created block list entry:", entry.id);

4. إرسال ملاحظات

أرسل ملاحظاتك على القرار لتحسين دقة التقييم.

POST /api/v1/feedback/decision/:id
const decisionId = "evt_ckm9876543210";
const idempotencyKey = `feedback-${decisionId}-${Date.now()}`;

const response = await fetch(
  `https://api.naiza.ai/api/v1/feedback/decision/${decisionId}`,
  {
    method: "POST",
    headers: {
      "x-api-key": process.env.NAIZA_API_KEY,
      "Idempotency-Key": idempotencyKey,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      label: "FRAUD",
      notes: "Customer confirmed this was fraudulent activity",
      externalCaseId: "case_12345",
    }),
  },
);

const feedback = await response.json();
console.log("Feedback submitted:", feedback.id);

5. إنشاء اشتراك Webhook

اشترك لتصلك إشعارات القرارات فور صدورها.

POST /api/v1/webhooks/subscriptions
const response = await fetch(
  "https://api.naiza.ai/api/v1/webhooks/subscriptions",
  {
    method: "POST",
    headers: {
      "x-api-key": process.env.NAIZA_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      url: "https://api.example.com/webhooks",
      eventTypes: ["EVENT_RISK_EVALUATED", "EVENT_FEEDBACK_SUBMITTED"],
    }),
  },
);

const subscription = await response.json();
console.log("Webhook subscription created:", subscription.id);
console.log("Store signing secret once:", subscription.signingSecret);

مثال تكامل كامل

مثال كامل يجمع العمليات الأساسية:

NaizaClient
class NaizaClient {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = "https://api.naiza.ai/api/v1";
  }

  async evaluateTransaction(transaction) {
    const response = await fetch(`${this.baseUrl}/decisions/evaluate`, {
      method: "POST",
      headers: {
        "x-api-key": this.apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(transaction),
    });

    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.error.message);
    }

    return response.json();
  }

  async getDecision(decisionId) {
    const response = await fetch(`${this.baseUrl}/decisions/${decisionId}`, {
      headers: { "x-api-key": this.apiKey },
    });

    return response.json();
  }

  async blockIP(ip, reason) {
    const response = await fetch(`${this.baseUrl}/lists/ip`, {
      method: "POST",
      headers: {
        "x-api-key": this.apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        ip,
        reason,
      }),
    });

    return response.json();
  }

  async submitFeedback(decisionId, label, notes) {
    const idempotencyKey = `feedback-${decisionId}-${Date.now()}`;

    const response = await fetch(
      `${this.baseUrl}/feedback/decision/${decisionId}`,
      {
        method: "POST",
        headers: {
          "x-api-key": this.apiKey,
          "Idempotency-Key": idempotencyKey,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ label, notes }),
      },
    );

    return response.json();
  }
}

// الاستخدام
const client = new NaizaClient(process.env.NAIZA_API_KEY);

// تقييم معاملة
const decision = await client.evaluateTransaction({
  eventName: "payment.attempt",
  customer: { externalId: "cust_123" },
  ip: "203.0.113.42",
});

console.log(`Decision: ${decision.decision}, Risk: ${decision.riskScore}`);

// إذا حُظرت، أضف إلى قائمة الحظر
if (decision.decision === "deny") {
  await client.blockIP("203.0.113.42", "High risk transaction");
}

// لاحقًا، قدّم ملاحظات
if (customerConfirmedFraud) {
  await client.submitFeedback(
    decision.correlationIds.eventId,
    "FRAUD",
    "Customer confirmed fraud",
  );
}

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

  • راجع أمثلة التكامل لمزيد من النماذج
  • تصفح مرجع API للاطلاع على التوثيق الكامل
  • اضبط Webhooks لتصلك الإشعارات فورًا
  • أضف جمع إشارات المتصفح عبر Web SDK
  • اقرأ أفضل الممارسات قبل التطبيق الفعلي للقرارات في الإنتاج