> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# واجهة برمجة تطبيقات مخاطر IP: الموقع وVPN ومراكز البيانات

> قيّم مخاطر عنوان IP في Didit باستخدام الموقع الجغرافي ومزود الخدمة وإشارات VPN وTor ومراكز البيانات والتهديدات وعدم تطابق الدولة المعلنة.

Use `POST /v3/ip/risk/` عندما يكون لدى الخادم الخلفي عنوان IP بالفعل ويحتاج إلى قرار مخاطر من الخادم إلى الخادم.

تتضمن الاستجابة تحديد الموقع الجغرافي، وملكية الشبكة، ومؤشرات VPN/Tor ومراكز البيانات، وبيانات التهديدات، و`country_mismatch` عندما ترسل دولة مُدّعاة.

## تفسير الاستجابة

* تكون قيمة `status` هي `In Review` عندما تتعارض الدولة المحددة مع `claimed_country`، أو عندما يرتبط العنوان ببنية تحتية لـ VPN أو Tor أو مراكز البيانات. وفي غير ذلك تكون `Approved`.
* يحتوي `ip.ip_country_code` على رمز الدولة المحددة. قارن الدول عبر `ip.country_mismatch` بدلاً من مقارنة أسماء الدول الخام بنفسك.
* يمثل `ip.latitude` و`ip.longitude` تحديداً جغرافياً تقريبياً للشبكة، وليس موقعاً دقيقاً للجهاز.
* `ip.is_vpn_or_tor` و`ip.is_data_center` و`ip.proxy_type` و`ip.threat` تحمل أدلة على مخاطر الشبكة.
* `ip.asn_number` و`ip.asn_organization` و`ip.connection_type` و`ip.carrier` تصف الشبكة التي ينتمي إليها العنوان.
* `request_id` هو معرّف جلسة API. خزّنه مع `vendor_data` إذا احتجت إلى ربط النتيجة بعمليات webhook لاحقة أو بنشاط لوحة التحكم.

> [!NOTE]
>
> الإثراء بالبيانات يتم بأفضل جهد ممكن. إذا لم يُرجع أي مصدر إثراء بيانات قابلة للاستخدام، تعيد endpoint استجابة مقبولة تتضمن `ip.ip_address: null` و`ip.country_mismatch: null` وكائن `ip.threat` فارغاً. قد تكون حقول الإثراء الفردية أيضاً `null` عندما تكون غير متاحة.

## استخبارات الجهاز

واجهة IP Risk API هي endpoint من الخادم إلى الخادم فقط. أما تحديد بصمة الجهاز فليس كذلك، لأن الخادم الخلفي لا يستطيع رصد إشارات المتصفح أو الجهاز بمفرده. بالنسبة إلى جلسات التدفق المستضاف وجلسات SDK، تعرض Didit حقول الجهاز التي جُمعت مسبقاً في استجابة الجلسة، ومنها `device_fingerprint` وتفاصيل الجهاز والمتصفح و`user_agent` والبيانات الخام للجهاز والتطابقات عبر الجلسات.

## سلوك البيئة التجريبية

تتحقق مفاتيح البيئة التجريبية من الطلب وتعيد بيانات مقبولة حتمية. لا تتصل هذه المفاتيح بخدمات الاستخبارات الخارجية، ولا تستهلك الرصيد، ولا تنشئ جلسة، ولا تساهم في Networks.

## الفوترة

تبلغ تكلفة استدعاءات IP Risk API ‏\$0.02 بحسب سعر القائمة. يصبح الطلب الفعلي قابلاً للفوترة بمجرد بدء البحث.


## OpenAPI

````yaml ar/openapi-25.json POST /v3/ip/risk/
openapi: 3.0.0
info:
  version: 3.0.0
  title: Didit Verification API
  description: API التحقق من الهوية. قم بالمصادقة باستخدام الرأس x-api-key.
servers:
  - url: https://verification.didit.me
security: []
tags: []
paths:
  /v3/ip/risk/:
    post:
      tags:
        - Standalone APIs
      summary: احتساب درجة المخاطر لعنوان IP
      description: >-
        إرجاع الموقع الجغرافي، وملكية الشبكة، ومؤشرات VPN/Tor ومراكز البيانات،
        وبيانات التهديدات، و`country_mismatch` لعنوان IP محدد. ينشئ هذا الـ
        endpoint جلسة API ويعيد معرفها كـ `request_id`.


        **القرار.** تكون `status` هي `In Review` عندما تتعارض الدولة المحددة مع
        `claimed_country`، أو عندما يرتبط العنوان ببنية تحتية لـ VPN أو Tor أو
        مركز بيانات. وإلا فإنها تكون `Approved`.


        **بذل أقصى جهد.** يُقدم إثراء IP بأقصى جهد ممكن. إذا لم يُرجع أي مصدر
        إثراء بيانات قابلة للاستخدام، يُرجع الـ endpoint استجابة مقبولة مع
        `ip.ip_address: null` و`ip.country_mismatch: null` وكائن `ip.threat`
        فارغ.


        **الفوترة.** تستخدم الاستدعاءات في بيئة الإنتاج أسعار IP Risk API. يكون
        الطلب خاضعاً للفوترة بمجرد بدء عملية البحث.


        **البيئة التجريبية.** تتحقق مفاتيح البيئة التجريبية من صحة الطلب وتعيد
        بيانات مقبولة محددة مسبقاً دون استهلاك أرصدة، أو إنشاء جلسة، أو المساهمة
        في Networks.


        **المصادقة.** أرسل مفتاح API الخاص بتطبيقك في `x-api-key`. تُرجع بيانات
        الاعتماد المفقودة أو غير الصالحة `403` - لا تُرجع هذه الـ API أبداً
        `401`.


        **حد المعدل.** ميزانية كتابة مشتركة تبلغ 300 طلب في الدقيقة لكل مفتاح
        API عبر جميع endpoints الخاصة بـ POST/PATCH/DELETE (تمتلك عمليات إنشاء
        المعاملات واستيعاب الأحداث ميزانية منفصلة تبلغ 600).
      operationId: post_v3ip_risk
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IPRiskRequest'
            examples:
              Minimal:
                summary: احتساب درجة لعنوان بالقيم الافتراضية
                value:
                  ip_address: 8.8.8.8
              With claimed country:
                summary: احتساب الدرجة مع تحديد دولة مدعاة لكشف عدم التطابق
                value:
                  ip_address: 8.8.8.8
                  claimed_country: ESP
                  user_agent: >-
                    Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)
                    AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.4
                    Safari/605.1.15
                  vendor_data: lead-123
      responses:
        '200':
          description: >-
            اكتمل تقييم المخاطر. افحص `status` لمعرفة القرار؛ رمز HTTP دائماً ما
            يكون `200` لعمليات البحث المكتملة.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IPRiskResponse'
              examples:
                Clean residential IP:
                  summary: عنوان السكن، الدولة المُصرَّح بها متطابقة
                  value:
                    request_id: 9a96ed2a-721e-4b86-8cbf-d61eda529279
                    status: Approved
                    ip:
                      status: Approved
                      ip_address: 192.0.2.10
                      ip_country: Spain
                      ip_country_code: ES
                      ip_state: Madrid
                      ip_city: Madrid
                      latitude: 40.4168
                      longitude: -3.7038
                      isp: Example Telecom
                      organization: Example Telecom SA
                      is_vpn_or_tor: false
                      is_data_center: false
                      time_zone: Europe/Madrid
                      time_zone_offset: '+0200'
                      asn_number: 3352
                      asn_organization: EXAMPLE-TELECOM
                      connection_type: broadband
                      carrier: Example Telecom
                      proxy_type: null
                      claimed_country: ESP
                      country_mismatch: false
                      threat: {}
                    vendor_data: lead-123
                    metadata: null
                    created_at: '2026-09-01T10:30:00.123456+00:00'
                Datacenter mismatch:
                  summary: عنوان مركز بيانات يتعارض مع الدولة المزعومة
                  value:
                    request_id: 5b1d4e9a-3c7b-4f8e-9a2d-1b0c9d8e7f6a
                    status: In Review
                    ip:
                      status: In Review
                      ip_address: 8.8.8.8
                      ip_country: United States
                      ip_country_code: US
                      ip_state: California
                      ip_city: Mountain View
                      latitude: 37.386
                      longitude: -122.0838
                      isp: Google
                      organization: Google LLC
                      is_vpn_or_tor: true
                      is_data_center: true
                      time_zone: America/Los_Angeles
                      time_zone_offset: '-0700'
                      asn_number: 15169
                      asn_organization: GOOGLE, US
                      connection_type: hosting
                      carrier: null
                      proxy_type: VPN
                      claimed_country: ESP
                      country_mismatch: true
                      threat:
                        is_proxy: true
                        is_data_center: true
                        is_tor: false
                    vendor_data: lead-126
                    metadata: null
                    created_at: '2026-09-01T10:30:00.123456+00:00'
        '400':
          $ref: '#/components/responses/IPRiskValidationError'
        '403':
          $ref: '#/components/responses/RiskPermissionDenied'
        '429':
          $ref: '#/components/responses/RateLimitedWrite'
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: curl
          label: curl
          source: |-
            curl -X POST https://verification.didit.me/v3/ip/risk/ \
              -H 'x-api-key: YOUR_API_KEY' \
              -H 'Content-Type: application/json' \
              -d '{
                "ip_address": "8.8.8.8",
                "claimed_country": "ESP",
                "user_agent": "Mozilla/5.0",
                "vendor_data": "lead-123"
              }'
        - lang: python
          label: Python
          source: |-
            from didit import Didit

            # Reads DIDIT_API_KEY.
            client = Didit()

            result = client.ip.assess_risk(
                ip_address="8.8.8.8",
            )
            print(result)
        - lang: javascript
          label: Node.js
          source: |-
            import Didit from "@didit-protocol/sdk-node";

            // Reads DIDIT_API_KEY.
            const didit = new Didit();

            const result = await didit.ip.assessRisk({
              ip_address: "8.8.8.8",
            });
            console.log(result);
        - lang: go
          label: Go
          source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IP.AssessRisk(ctx, didit.IPRiskRequest{\n\tIPAddress: \"8.8.8.8\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)"
        - lang: java
          label: Java
          source: |-
            import me.didit.Didit;
            import me.didit.types.IPRiskRequest;

            // Reads DIDIT_API_KEY.
            Didit client = new Didit();

            var result = client.ip().assessRisk(IPRiskRequest.builder()
                    .ipAddress("8.8.8.8")
                    .build());
            System.out.println(result);
        - lang: php
          label: PHP
          source: |-
            <?php

            require 'vendor/autoload.php';

            use Didit\DiditClient;

            // Reads DIDIT_API_KEY.
            $didit = new DiditClient();

            $result = $didit->ip->assessRisk([
                'ip_address' => '8.8.8.8',
            ]);
            print_r($result->toArray());
        - lang: ruby
          label: Ruby
          source: |-
            require "didit"

            # Reads DIDIT_API_KEY.
            didit = Didit::Client.new

            result = didit.ip.assess_risk(ip_address: "8.8.8.8")
            puts result.to_h
        - lang: csharp
          label: .NET
          source: |-
            using System;
            using System.Text.Json;
            using Didit;

            // Reads DIDIT_API_KEY.
            using var client = new DiditClient();

            var result = await client.Ip.AssessRiskAsync(new IPRiskRequest
            {
                IpAddress = "8.8.8.8",
            });
            Console.WriteLine(JsonSerializer.Serialize(result));
components:
  schemas:
    IPRiskRequest:
      type: object
      required:
        - ip_address
      properties:
        ip_address:
          type: string
          format: ip
          description: عنوان IPv4 أو IPv6 لاحتساب درجته.
          example: 8.8.8.8
        claimed_country:
          type: string
          maxLength: 3
          description: >-
            دولة اختيارية وفق معيار ISO 3166-1 alpha-2 أو alpha-3 يدّعيها
            المستخدم أو الجلسة. تُستخدم لحساب `country_mismatch`.
          example: ESP
        user_agent:
          type: string
          maxLength: 512
          description: >-
            وكيل المستخدم الذي رصدته الواجهة الخلفية لديك. يتم تخزينه كسياق
            للطلب؛ ولا يوفر بصمة للجهاز.
        vendor_data:
          type: string
          description: >-
            مرجعك الثابت لهذا الطلب. يتم تخزينه في جلسة API وإعادته في
            الاستجابة.
        metadata:
          type: object
          nullable: true
          additionalProperties: true
          description: >-
            البيانات الوصفية بتنسيق JSON غير الحساسة الخاصة بك. يتم تخزينها في
            جلسة API وإعادتها في الاستجابة.
    IPRiskResponse:
      type: object
      required:
        - request_id
        - status
        - created_at
      properties:
        request_id:
          type: string
          format: uuid
          description: >-
            معرّف جلسة API التي تم إنشاؤها لهذا الطلب. احفظه مع `vendor_data`
            إذا كنت بحاجة إلى ربط النتيجة بـ webhooks اللاحقة أو نشاط لوحة
            التحكم.
        status:
          type: string
          enum:
            - Approved
            - In Review
          description: >-
            القرار لجلسة API هذه: `In Review` عند وجود مخاطر تتعلق بالشبكة أو
            عدم تطابق الدولة، وإلا فـ `Approved`.
        vendor_data:
          type: string
          nullable: true
          description: >-
            نسخة مطابقة من `vendor_data` التي أرسلتها، وتكون `null` عند عدم
            إرسال أي منها.
        metadata:
          type: object
          nullable: true
          additionalProperties: true
          description: >-
            نسخة مطابقة من `metadata` التي أرسلتها، وتكون `null` عند عدم إرسال
            أي منها.
        created_at:
          type: string
          format: date-time
          description: الطابع الزمني لهذه الاستجابة.
        ip:
          type: object
          description: >-
            نتيجة مخاطر عنوان IP. قد تكون حقول الإثراء الفردية `null` عندما لا
            يُرجع البحث أي بيانات قابلة للاستخدام.
          required:
            - status
            - threat
          properties:
            status:
              type: string
              enum:
                - Approved
                - In Review
              description: >-
                `In Review` عندما تتعارض الدولة المحددة مع `claimed_country`، أو
                عندما يرتبط العنوان ببنية تحتية لـ VPN أو Tor أو مراكز البيانات.
                وخلاف ذلك `Approved`.
            ip_address:
              type: string
              nullable: true
              description: >-
                العنوان الذي تم احتساب درجاته. `null` عندما لا يُرجع أي مصدر
                إثراء بيانات قابلة للاستخدام.
            ip_country:
              type: string
              nullable: true
              description: اسم الدولة المحدد.
            ip_country_code:
              type: string
              nullable: true
              description: >-
                رمز الدولة المحدد. قارن الدول من خلال `country_mismatch` بدلاً
                من مقارنة نصوص الدول الخام بنفسك.
            ip_state:
              type: string
              nullable: true
              description: الولاية أو المنطقة المحددة.
            ip_city:
              type: string
              nullable: true
              description: المدينة المحددة.
            latitude:
              type: number
              nullable: true
              description: موقع جغرافي تقريبي للشبكة، وليس موقعاً دقيقاً للجهاز.
            longitude:
              type: number
              nullable: true
              description: موقع جغرافي تقريبي للشبكة، وليس موقعاً دقيقاً للجهاز.
            isp:
              type: string
              nullable: true
              description: مزود خدمة الإنترنت الذي يخدم العنوان.
            organization:
              type: string
              nullable: true
              description: المؤسسة المالكة لنطاق العناوين.
            is_vpn_or_tor:
              type: boolean
              nullable: true
              description: >-
                تكون القيمة `true` عندما يكون العنوان مرتبطاً ببنية تحتية لـ VPN
                أو Tor.
            is_data_center:
              type: boolean
              nullable: true
              description: >-
                تكون القيمة `true` عندما ينتمي العنوان إلى شبكة استضافة أو مركز
                بيانات.
            time_zone:
              type: string
              nullable: true
              description: المنطقة الزمنية للموقع الجغرافي المحدد.
            time_zone_offset:
              type: string
              nullable: true
              description: إزاحة UTC للموقع المحدد.
            asn_number:
              type: number
              nullable: true
              description: رقم النظام المستقل.
            asn_organization:
              type: string
              nullable: true
              description: المؤسسة التي تشغّل النظام المستقل.
            connection_type:
              type: string
              nullable: true
              description: تصنيف الاتصال (مثل `cellular`، `hosting`).
            carrier:
              type: string
              nullable: true
              description: مشغل شبكة الجوال عندما يكون العنوان على شبكة جوال.
            proxy_type:
              type: string
              nullable: true
              description: تصنيف البروكسي عندما يكون العنوان خلف بروكسي.
            claimed_country:
              type: string
              nullable: true
              description: نسخة مطابقة من `claimed_country` التي أرسلتها.
            country_mismatch:
              type: boolean
              nullable: true
              description: >-
                تكون `true` عندما تختلف الدولة المحددة عن `claimed_country`.
                وتكون `null` عند عدم توفر بيانات إثراء أو عدم وجود دولة معلنة.
            threat:
              type: object
              additionalProperties: true
              description: >-
                أدلة تهديدات الشبكة بصيغة حرة من مصدر الإثراء (مثل `is_proxy` أو
                `is_tor`). يكون كائناً فارغاً عند عدم توفر بيانات إثراء. تعامل
                معها كتفاصيل تشخيصية وليست عقداً ثابتاً.
  responses:
    IPRiskValidationError:
      description: فشل التحقق من صحة الطلب.
      content:
        application/json:
          examples:
            Missing IP address:
              summary: عنوان IP مفقود
              value:
                ip_address:
                  - This field is required.
            Invalid IP address:
              summary: عنوان IP غير صالح
              value:
                ip_address:
                  - Enter a valid IPv4 or IPv6 address.
            Country hint too long:
              summary: تلميح الدولة طويل جدًا
              value:
                claimed_country:
                  - Ensure this field has no more than 3 characters.
    RiskPermissionDenied:
      description: >-
        مفتاح API مفقود أو غير صالح، أو لا تستطيع المؤسسة تغطية البحث المباشر.
        لا تُرجع هذه API أبداً الرمز `401`.
      content:
        application/json:
          examples:
            Missing or invalid API key:
              summary: لا يوجد رأس `x-api-key`، أو أن المفتاح غير صالح أو ملغى
              value:
                detail: You do not have permission to perform this action.
            Not enough credits:
              summary: رصيد المؤسسة لا يمكنه تغطية سعر البحث
              value:
                error: You don't have enough credits to perform this request.
    RateLimitedWrite:
      description: >-
        تم تجاوز حد الكتابة المشترك البالغ 300 طلب في الدقيقة لكل مفتاح API.
        التزم بالمدة المحددة في `Retry-After` قبل إعادة المحاولة.
      content:
        application/json:
          schema:
            type: object
            required:
              - detail
            properties:
              detail:
                type: string
          example:
            detail: >-
              Write request rate limit exceeded. You can make up to 300 requests
              per minute.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        مفتاح API الخاص بتطبيقك، من Developers -> API keys في Business Console.
        يمتلك المفتاح الأساسي وصولاً كاملاً. يمكن تحديد نطاق المفتاح المسمى: لا
        شيء، أو قراءة، أو كتابة لكل مورد، ومحدوداً ببعض مسارات العمل أو بالجلسات
        المقبولة، وبقائمة من عناوين IP، وبتاريخ انتهاء الصلاحية. يشير 401 إلى أن
        المفتاح غير صحيح أو ملغى أو منتهي الصلاحية؛ ويشير 403 إلى أنه لم يتم
        إرسال أي مفتاح، أو أن المفتاح ليس لديه حق الوصول إلى هذا المورد أو
        الإجراء، أو أن الطلب جاء من عنوان خارج قائمة عناوين IP الخاصة به؛ ويشير
        404 في مسار جلسة إلى أن الجلسة خارج مسارات العمل أو الحالات الخاصة
        بالمفتاح. يتلقى المفتاح الذي لا يمتلك حق الوصول إلى الوسائط عناوين URL
        للصور ومقاطع الفيديو وملفات PDF كـ null، ويتلقى المفتاح الذي لا يمتلك
        إذن كتابة للجلسات روابط الجلسة وtoken كـ null. راجع
        https://docs.didit.me/console/api-keys.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.