> ## 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. بدءاً من $3.50 لكل استدعاء، دون عقود أو حد أدنى.

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

## التغطية

* **التغطية:** \~ 100%
* **الدولة:** فنلندا
* **معرّف الخدمة:** `fin_national_id`
* **نطاق البيانات:** الهوية
* **الفئة:** NationalIDRegistry

## المدخلات

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

* **المدخلات المطلوبة:** `first_name`، `last_name`، `date_of_birth`، `national_id`
* **المدخلات الاختيارية:** `address.street_1`، `address.street_2`، `address.city`، `address.region`، `address.postal_code`، `vendor_data`
* **الموافقة:** مطلوبة
* **إتاحة سير العمل:** متاحة في سير العمل
* **التغطية:** \~ 100%
* **السعر:** \$3.50 لكل استعلام ناجح

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

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

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

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

مثال: `FIN`

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

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

مثال: `fin_national_id`

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

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

مثال: `true`

**first\_name** `string` *required* (default: John)

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

مثال: `John`

**last\_name** `string` *required* (default: Doe)

اسم العائلة المراد التحقق منه.

مثال: `Doe`

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

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

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

**national\_id** `string` *required* (default: 010190-123A)

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

مثال: `010190-123A`

**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"}`

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

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

مثال: `user-1234`

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

* حقل `address` اختياري لهذه الخدمة. يمكنك إرسال سلسلة `address` كاملة واحدة، وستقوم Didit بتقسيمها إلى عناصر عنوان منظَّمة متى أمكن ذلك، أو يمكنك إرسال الحقول المنظَّمة بشكل صريح.
* يجب أن يتطابق `national_id` مع `(?:\d{6}[-+A]\d{3}[0-9A-Z]|\d{6}\d{3}[0-9A-Z])`.
* بالنسبة إلى خدمات العناوين، أرسل حقول العنوان المنظَّمة بدلاً من سلسلة `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=FIN" \
  -F "services=fin_national_id" \
  -F "vendor_data=user-1234" \
  -F "consent=true" \
  -F "first_name=John" \
  -F "last_name=Doe" \
  -F "date_of_birth=1990-01-01" \
  -F "national_id=010190-123A"
```

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

# Reads DIDIT_API_KEY.
client = Didit()

result = client.database_validation.validate(
    issuing_state="FIN",
    services=["fin_national_id"],
    consent=True,
    first_name="John",
    last_name="Doe",
    date_of_birth="1990-01-01",
    national_id="010190-123A",
    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: "FIN",
  services: ["fin_national_id"],
  consent: true,
  first_name: "John",
  last_name: "Doe",
  date_of_birth: "1990-01-01",
  national_id: "010190-123A",
  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: "FIN",
	Services:     didit.Some([]string{"fin_national_id"}),
	Consent:      didit.Bool(true),
	FirstName:    didit.String("John"),
	LastName:     didit.String("Doe"),
	DateOfBirth:  didit.String("1990-01-01"),
	NationalID:   didit.String("010190-123A"),
	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("FIN")
        .services(List.of("fin_national_id"))
        .consent(true)
        .firstName("John")
        .lastName("Doe")
        .dateOfBirth(LocalDate.parse("1990-01-01"))
        .nationalId("010190-123A")
        .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' => 'FIN',
    'services' => ['fin_national_id'],
    'consent' => true,
    'first_name' => 'John',
    'last_name' => 'Doe',
    'date_of_birth' => '1990-01-01',
    'national_id' => '010190-123A',
    '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: "FIN",
  services: ["fin_national_id"],
  consent: true,
  first_name: "John",
  last_name: "Doe",
  date_of_birth: "1990-01-01",
  national_id: "010190-123A",
  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 = "FIN",
    Services = new string[] { "fin_national_id" },
    Consent = true,
    FirstName = "John",
    LastName = "Doe",
    DateOfBirth = "1990-01-01",
    NationalId = "010190-123A",
    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": "FIN",
  "match_type": "full_match",
  "validations": [
    {
      "outcome_code": "MATCH",
      "service_id": "fin_national_id",
      "service_name": "Finland National ID",
      "source_data": {
        "address": "123 Sample Street",
        "date_of_birth": "1990-01-01",
        "first_name": "John",
        "identification_number": "SAMPLE-ID-12345",
        "last_name": "Doe"
      },
      "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": "FIN",
  "match_type": "partial_match",
  "validations": [
    {
      "outcome_code": "PARTIAL_MATCH",
      "service_id": "fin_national_id",
      "service_name": "Finland National ID",
      "source_data": {
        "address": "123 Sample Street",
        "date_of_birth": "1990-01-01",
        "first_name": "John",
        "identification_number": "SAMPLE-ID-12345",
        "last_name": "Doe"
      },
      "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": "FIN",
  "match_type": "no_match",
  "validations": [
    {
      "outcome_code": "NO_MATCH",
      "service_id": "fin_national_id",
      "service_name": "Finland 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` على ما يُرجعه السجل. يوثّق المثال المُنشأ لـ `fin_national_id` حالياً هذه البنية الموحّدة:

* `address`
* `date_of_birth`
* `first_name`
* `identification_number`
* `last_name`

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

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

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

## مواصلة القراءة

* [نظرة عامة على التحقق من قواعد البيانات في فنلندا](https://docs.didit.me/api-reference/database-validation/finland.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.