> ## 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.

# التحقق من الهوية الوطنية الماليزية عبر API: مطابقة البيانات

> التحقق من الهوية الوطنية الماليزية عبر قواعد البيانات الرسمية من Didit. بدءاً من $0.59 لكل عملية، دون عقود أو حد أدنى.

يتحقق من بيانات الإدخال مقابل قاعدة بيانات تابعة لجهة حكومية تضم بيانات المواطنين الماليزيين. يوفّر Didit هذه الخدمة عبر `POST /v3/database-validation/` لتتمكن من التحقق من البيانات المُرسلة مقابل المصدر الرسمي الموثوق، واستلام نتائج مطابقة موحّدة.

## التغطية

* **التغطية:** > 75%
* **الدولة:** ماليزيا
* **معرّف الخدمة:** `mys_national_id`
* **نطاق البيانات:** الهوية
* **الفئة:** NationalIDRegistry

## المدخلات

| الحقل | مطلوب | مثال |
| - | -: | - |
| `full_name` | نعم | `John Doe` |
| `date_of_birth` | نعم | `1990-01-01` |
| `national_id` | نعم | `111111111111` |
| `address.street_1` | لا | `123 Sample Street` |
| `address.street_2` | لا | `Unit 4` |
| `address.city` | لا | `Sample City` |
| `address.region` | لا | `Sample State` |
| `address.postal_code` | لا | `10001` |
| `phone` | لا | `+15550101000` |
| `vendor_data` | لا | `user-1234` |

* **المدخلات المطلوبة:** `full_name` و`date_of_birth` و`national_id`
* **المدخلات الاختيارية:** `address.street_1` و`address.street_2` و`address.city` و`address.region` و`address.postal_code` و`phone` و`vendor_data`
* **الموافقة:** مطلوبة
* **التوفر في سير العمل:** متاح في سير العمل
* **التغطية:** > 75%
* **السعر:** \$0.59 لكل استعلام ناجح

لا يحتوي كل مستند تقبله هذه الخدمة على المعرّف الذي تستعلم به. عندما لا يُستخرج المعرّف من المستند، يُسجَّل الفحص بصفته **غير منطبق**، فلا يتم الاستعلام عن أي قاعدة بيانات ولا تُحتسب أي رسوم، وهو ما يمثّل في بعض الدول نسبة كبيرة من المستخدمين الفعليين. ولتغطية هؤلاء المستخدمين، اجمع المعرّف أيضًا من إجابة في الاستبيان، أو من حقل استخراج في Document AI، أو من قيمة ترسلها عند إنشاء الجلسة، ثم قم بربطها في خطوة التحقق من قواعد البيانات.

## معاملات الجسم

**issuing\_state** `string` *required* (default: MYS)

رمز الدولة وفق ISO 3166-1 alpha-3 لخدمة قاعدة البيانات هذه.

مثال: `MYS`

**services** `string` *required* (default: mys\_national\_id)

مصفوفة تحتوي على معرّف هذه الخدمة. تثبيت الخدمة يُبقي الطلب مقصورًا على قاعدة البيانات المحددة هذه تحديدًا.

مثال: `mys_national_id`

**consent** `boolean` *required* (default: true)

موافقة صريحة من المستخدم النهائي على هذه الخدمة.

مثال: `true`

**full\_name** `string` *required* (default: John Doe)

الاسم القانوني الكامل المراد التحقق منه.

مثال: `John Doe`

**date\_of\_birth** `string` *required* (default: 1990-01-01)

تاريخ الميلاد بصيغة `YYYY-MM-DD`.

مثال: `1990-01-01`

**national\_id** `string` *required* (default: 111111111111)

رقم الهوية الوطنية لهذه الخدمة.

مثال: `111111111111`

**address** `object`

كائن عنوان سكني منظّم. استخدم `street_1` و`street_2` و`city` و`region` و`postal_code` و`country`. ما زال يُقبل عنوان قديم كامل في سلسلة نصية واحدة، لكنه غير مستحسن.

مثال: `{"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}`

**phone** `string`

رقم الهاتف بالصيغة الدولية.

مثال: `+15550101000`

**vendor\_data** `string` (default: user-1234)

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

مثال: `user-1234`

## قواعد المدخلات وملاحظات التحقق

* الحقل `address` اختياري لهذه الخدمة. يمكنك إرسال سلسلة `address` واحدة كاملة، وسيقوم Didit بتقسيمها إلى عناصر عنوان منظمة عند الإمكان، أو يمكنك إرسال الحقول المنظمة للعنوان صراحةً.
* يجب أن يحتوي `national_id` على أرقام فقط؛ أزل المسافات والشرطات وعلامات الترقيم قبل إرسال الطلب.
* يجب أن يكون طول `national_id` 12 حرفًا بالضبط.
* بالنسبة إلى خدمات قواعد البيانات التي تعتمد على العنوان، أرسل حقول العنوان المنظمة بدلًا من سلسلة `address` واحدة متى أمكن.
* يمثّل `address.street_1` عنوان الشارع، ويشمل رقم المبنى ونوع الشارع.
* يمثّل `address.street_2` الشقة أو الوحدة أو المبنى أو الطابق أو أي سطر إضافي للعنوان. أرسله فقط عندما يتوفر لديك.
* يمثّل `address.city` المدينة أو الضاحية أو المنطقة أو الحي أو المجاورة.
* يمثّل `address.region` الولاية أو المحافظة أو الإقليم أو البلدة.
* يمثّل `address.postal_code` الرمز البريدي.
* تتطلب خدمات قواعد البيانات المعتمدة على العنوان على الأقل عنوان الشارع والرمز البريدي؛ والطلبات المرفوضة قبل الاستعلام عن المصدر لا تُحتسب رسومها.

## كيفية الاستدعاء

```bash cURL theme={null}
curl -X POST "https://verification.didit.me/v3/database-validation/" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "issuing_state=MYS" \
  -F "services=mys_national_id" \
  -F "vendor_data=user-1234" \
  -F "consent=true" \
  -F "full_name=John Doe" \
  -F "date_of_birth=1990-01-01" \
  -F "national_id=111111111111"
```

```python Python theme={null}
from didit import Didit

# Reads DIDIT_API_KEY.
client = Didit()

result = client.database_validation.validate(
    issuing_state="MYS",
    services=["mys_national_id"],
    consent=True,
    full_name="John Doe",
    date_of_birth="1990-01-01",
    national_id="111111111111",
    vendor_data="user-1234",
)
print(result)
```

```javascript Node.js theme={null}
import Didit from "@didit-protocol/sdk-node";

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

const result = await didit.databaseValidation.validate({
  issuing_state: "MYS",
  services: ["mys_national_id"],
  consent: true,
  full_name: "John Doe",
  date_of_birth: "1990-01-01",
  national_id: "111111111111",
  vendor_data: "user-1234",
});
console.log(result);
```

```go Go theme={null}
ctx := context.Background()
// Reads DIDIT_API_KEY.
client := didit.NewClient()

result, err := client.DatabaseValidation.Validate(ctx, didit.DatabaseValidationValidateParams{
	IssuingState: "MYS",
	Services:     didit.Some([]string{"mys_national_id"}),
	Consent:      didit.Bool(true),
	FullName:     didit.String("John Doe"),
	DateOfBirth:  didit.String("1990-01-01"),
	NationalID:   didit.String("111111111111"),
	VendorData:   didit.String("user-1234"),
})
if err != nil {
	log.Fatal(err)
}
fmt.Printf("%+v\n", result)
```

```java Java theme={null}
import java.time.LocalDate;
import java.util.List;
import me.didit.Didit;
import me.didit.types.DatabaseValidationValidateParams;

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

var result = client.databaseValidation().validate(DatabaseValidationValidateParams.builder()
        .issuingState("MYS")
        .services(List.of("mys_national_id"))
        .consent(true)
        .fullName("John Doe")
        .dateOfBirth(LocalDate.parse("1990-01-01"))
        .nationalId("111111111111")
        .vendorData("user-1234")
        .build());
System.out.println(result);
```

```php PHP theme={null}
<?php

require 'vendor/autoload.php';

use Didit\DiditClient;

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

$result = $didit->databaseValidation->validate([
    'issuing_state' => 'MYS',
    'services' => ['mys_national_id'],
    'consent' => true,
    'full_name' => 'John Doe',
    'date_of_birth' => '1990-01-01',
    'national_id' => '111111111111',
    'vendor_data' => 'user-1234',
]);
print_r($result->toArray());
```

```ruby Ruby theme={null}
require "didit"

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

result = didit.database_validation.validate(
  issuing_state: "MYS",
  services: ["mys_national_id"],
  consent: true,
  full_name: "John Doe",
  date_of_birth: "1990-01-01",
  national_id: "111111111111",
  vendor_data: "user-1234"
)
puts result.to_h
```

```csharp .NET theme={null}
using System;
using System.Text.Json;
using Didit;

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

var result = await client.DatabaseValidation.ValidateAsync(new DatabaseValidationValidateParams
{
    IssuingState = "MYS",
    Services = new string[] { "mys_national_id" },
    Consent = true,
    FullName = "John Doe",
    DateOfBirth = "1990-01-01",
    NationalId = "111111111111",
    VendorData = "user-1234",
});
Console.WriteLine(JsonSerializer.Serialize(result));
```

تُرجع كل عملية استدعاء ناجحة الاستجابة HTTP `200`. يوضح الحقل **`outcome_code`** ما حدث فعلاً، فيميّز على سبيل المثال بين عدم تطابق بيومتري حقيقي (`BIOMETRIC_NO_MATCH`) وصورة سيلفي تعذّر قراءتها (`BIOMETRIC_IMAGE_UNUSABLE`). تمثل `status` المعروضة الحالة الافتراضية للميزة، ويمكن أن تتجاوزها [إجراءات المطابقة الجزئية / عدم المطابقة](https://docs.didit.me/ar/core-technology/database-validation/database-validation-warnings.md) التي تضبطها.

**`MATCH`** — أكّد السجل الهوية وتطابقت جميع الحقول التي جرى فحصها.

```json 200 OK — MATCH theme={null}
{
  "request_id": "req_01H…",
  "status": "Approved",
  "issuing_state": "MYS",
  "match_type": "full_match",
  "validations": [
    {
      "outcome_code": "MATCH",
      "service_id": "mys_national_id",
      "service_name": "Malaysia National ID",
      "source_data": {
        "address": "123 Sample Street",
        "address_match_score": "1.000",
        "city": "Sample City",
        "date_of_birth": "1990-01-01",
        "identification_number": "SAMPLE-ID-12345",
        "postal_code": "10001",
        "state": "Sample State",
        "street": "sample_value"
      },
      "validation": {
        "date_of_birth": "full_match",
        "full_name": "full_match",
        "identification_number": "full_match"
      }
    }
  ]
}
```

**`PARTIAL_MATCH`** — وُجد رقم الهوية، لكن حقلاً واحداً أو أكثر من الحقول الشخصية (عادةً الاسم أو تاريخ الميلاد) لم تتطابق تماماً.

```json 200 OK — PARTIAL_MATCH theme={null}
{
  "request_id": "req_01H…",
  "status": "In Review",
  "issuing_state": "MYS",
  "match_type": "partial_match",
  "validations": [
    {
      "outcome_code": "PARTIAL_MATCH",
      "service_id": "mys_national_id",
      "service_name": "Malaysia National ID",
      "source_data": {
        "address": "123 Sample Street",
        "address_match_score": "1.000",
        "city": "Sample City",
        "date_of_birth": "1990-01-01",
        "identification_number": "SAMPLE-ID-12345",
        "postal_code": "10001",
        "state": "Sample State",
        "street": "sample_value"
      },
      "validation": {
        "date_of_birth": "full_match",
        "full_name": "no_match",
        "identification_number": "full_match"
      }
    }
  ]
}
```

**`NO_MATCH`** — لم يُرجع السجل أي تطابق للبيانات المُرسلة.

```json 200 OK — NO_MATCH theme={null}
{
  "request_id": "req_01H…",
  "status": "Declined",
  "issuing_state": "MYS",
  "match_type": "no_match",
  "validations": [
    {
      "outcome_code": "NO_MATCH",
      "service_id": "mys_national_id",
      "service_name": "Malaysia National ID",
      "source_data": {
        "date_of_birth": "NO_MATCH",
        "full_name": "NO_MATCH",
        "identification_number": "NO_MATCH"
      },
      "validation": {
        "date_of_birth": "no_match",
        "full_name": "no_match",
        "identification_number": "no_match"
      }
    }
  ]
}
```

## البيانات المُرجعة

تعتمد الحقول الدقيقة الظاهرة في `source_data` على ما يُرجعه السجل. يوثّق المثال المُولّد لـ `mys_national_id` حالياً هذا الشكل الموحّد:

* `address`
* `address_match_score`
* `city`
* `date_of_birth`
* `identification_number`
* `postal_code`
* `state`
* `street`

## الأسعار واتفاقيات مستوى الخدمة

لا تُحتسب استعلامات الهوية الوطنية الماليزية إلا عندما تستلم Didit نتيجة حاسمة من مصدر التحقق.

* **السعر لكل استدعاء:** \$0.59 USD.
* **الفوترة:** لكل استعلام ناجح. لا يُحتسب أي رسوم عندما يتعذّر الوصول إلى السجل، أو عند غياب الحقول المطلوبة، أو عندما يُرفض الطلب قبل وصوله إلى المصدر.
* **زمن الاستجابة:** المعتاد عند p95 أقل من ثانيتين.
* **التوفّر:** 99.9% لكل ربع سنة من جهة Didit؛ ويختلف توفّر المصدر النهائي حسب الدولة ومجموعة البيانات.

## متابعة القراءة

* [نظرة عامة على التحقق من قواعد البيانات في ماليزيا](https://docs.didit.me/api-reference/database-validation/malaysia.md)
* [نظرة عامة على التحقق من قواعد البيانات](https://docs.didit.me/ar/core-technology/database-validation/overview.md)
* [رموز النتائج](https://docs.didit.me/ar/core-technology/database-validation/database-validation-outcome-codes.md)


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