كل المستندات

بداية سريعة

العمليات الشائعة للأحداث والقرارات والقوائم والملاحظات.

البدء السريع

العمليات الشائعة التي ستنفّذها مع واجهة نيزا.

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
  • اقرأ أفضل الممارسات قبل فرض القرارات في الإنتاج