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

# Unico IDCloud: التحقق من CPF وسيلفي في البرازيل

> استعلام من قاعدة البيانات الرسمية في البرازيل عبر Didit باستخدام CPF وسيلفي من Unico IDCloud. من $0.20 لكل عملية، دون عقود أو حد أدنى.

التحقق البيومتري عبر Unico IDCloud: يطابق صورة السيلفي الخاصة بالمستخدم مع الوجه المسجّل لرقم CPF الخاص به، ويُعيد ما إذا كان الشخص نفسه، أو ليس الشخص نفسه، أو أن النتيجة غير حاسمة. تتيح لك Didit الوصول إلى هذه الخدمة عبر `POST /v3/database-validation/` للتحقق من البيانات المُرسلة مقابل المصدر الموثوق والحصول على نتائج مطابقة موحّدة. تنسيق الإدخال: يقبل `tax_number` رقم CPF البرازيلي (11 رقمًا بالضبط).

## التغطية

* **التغطية:** 96%
* **الدولة:** البرازيل
* **معرّف الخدمة:** `bra_unico_idcloud`
* **نطاق البيانات:** الهوية
* **الفئة:** BiometricRiskScore

يُعثر على نحو 96% من حاملي CPF البرازيليين في السجل البيومتري لدى Unico، وهو ما يعادل ضعف نطاق الوصول تقريبًا مقارنةً بمصدر مطابقة الوجه الحكومي [Datavalid](https://docs.didit.me/ar/api-reference/database-validation/brazil/cpf-facial.md) الذي يغطي نحو 50%.

## المدخلات

| الحقل | مطلوب | مثال |
| - | -: | - |
| `tax_number` | نعم | `11111111111` |
| `selfie` | نعم | `@./selfie.jpg` |
| `first_name` | لا | `John` |
| `last_name` | لا | `Doe` |
| `full_name` | لا | `John Doe` |
| `date_of_birth` | لا | `1990-01-01` |
| `vendor_data` | لا | `user-1234` |

* **المدخلات المطلوبة:** `tax_number` و`selfie`
* **المدخلات الاختيارية:** `first_name` و`last_name` و`full_name` و`date_of_birth` و`vendor_data`
* **الموافقة:** مطلوبة
* **التوفر في سير العمل:** متاح في سير العمل
* **التغطية:** 96%
* **السعر:** \$0.20 لكل استعلام ناجح

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

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

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

مثال: `BRA`

**services** `string` *required* (default: bra\_unico\_idcloud)

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

مثال: `bra_unico_idcloud`

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

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

مثال: `true`

**tax\_number** `string` *required* (default: 11111111111)

الرقم الضريبي أو رقم التعريف المالي.

مثال: `11111111111`

**selfie** `file` *required*

ملف صورة السيلفي المراد رفعه للتحقق البيومتري من قاعدة البيانات. الصيغ المقبولة: JPEG أو PNG أو WebP.

مثال: `@./selfie.jpg`

**first\_name** `string`

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

مثال: `John`

**last\_name** `string`

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

مثال: `Doe`

**full\_name** `string`

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

مثال: `John Doe`

**date\_of\_birth** `string`

تاريخ الميلاد بتنسيق `YYYY-MM-DD`.

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

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

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

مثال: `user-1234`

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

* رقم CPF البرازيلي (11 رقمًا بالضبط)
* يجب أن يحتوي `tax_number` على أرقام فقط؛ أزل المسافات والشرطات وعلامات الترقيم قبل إرسال الطلب.
* يجب أن يكون طول `tax_number` 11 حرفًا بالضبط.

## طريقة الاستدعاء

```bash cURL theme={null}
curl -X POST "https://verification.didit.me/v3/database-validation/" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "issuing_state=BRA" \
  -F "services=bra_unico_idcloud" \
  -F "vendor_data=user-1234" \
  -F "consent=true" \
  -F "tax_number=11111111111" \
  -F "selfie=@./selfie.jpg"
```

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

# Reads DIDIT_API_KEY.
client = Didit()

result = client.database_validation.validate(
    issuing_state="BRA",
    services=["bra_unico_idcloud"],
    consent=True,
    tax_number="11111111111",
    vendor_data="user-1234",
    selfie=open("selfie.jpg", "rb"),
)
print(result)
```

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

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

const result = await didit.databaseValidation.validate({
  issuing_state: "BRA",
  services: ["bra_unico_idcloud"],
  consent: true,
  tax_number: "11111111111",
  vendor_data: "user-1234",
  selfie: await fileFromPath("selfie.jpg"),
});
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: "BRA",
	Services:     didit.Some([]string{"bra_unico_idcloud"}),
	Consent:      didit.Bool(true),
	TaxNumber:    didit.String("11111111111"),
	VendorData:   didit.String("user-1234"),
	Selfie:       didit.Some(didit.FileFromPath("selfie.jpg")),
})
if err != nil {
	log.Fatal(err)
}
fmt.Printf("%+v\n", result)
```

```java Java theme={null}
import java.nio.file.Path;
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("BRA")
        .services(List.of("bra_unico_idcloud"))
        .consent(true)
        .taxNumber("11111111111")
        .vendorData("user-1234")
        .selfie(Path.of("selfie.jpg"))
        .build());
System.out.println(result);
```

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

require 'vendor/autoload.php';

use Didit\DiditClient;
use Didit\File;

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

$result = $didit->databaseValidation->validate([
    'issuing_state' => 'BRA',
    'services' => ['bra_unico_idcloud'],
    'consent' => true,
    'tax_number' => '11111111111',
    'vendor_data' => 'user-1234',
    'selfie' => File::fromPath('selfie.jpg'),
]);
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: "BRA",
  services: ["bra_unico_idcloud"],
  consent: true,
  tax_number: "11111111111",
  vendor_data: "user-1234",
  selfie: Pathname("selfie.jpg")
)
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 = "BRA",
    Services = new string[] { "bra_unico_idcloud" },
    Consent = true,
    TaxNumber = "11111111111",
    VendorData = "user-1234",
    Selfie = FileUpload.FromPath("selfie.jpg"),
});
Console.WriteLine(JsonSerializer.Serialize(result));
```

يعيد كل استدعاء ناجح رمز الحالة HTTP `200`. يوضح الحقل **`outcome_code`** ما حدث فعلًا، فيميّز مثلًا بين عدم تطابق بيومتري حقيقي (`BIOMETRIC_NO_MATCH`) وصورة سيلفي تعذّرت قراءتها (`BIOMETRIC_IMAGE_UNUSABLE`). الحالة `status` المعروضة هي حالة الميزة الافتراضية، ويمكن لإجراءات [Partial Match / No Match](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": "BRA",
  "match_type": "full_match",
  "validations": [
    {
      "outcome_code": "MATCH",
      "service_id": "bra_unico_idcloud",
      "service_name": "BRA - Unico IDCloud (CPF + selfie)",
      "source_data": {
        "unico_face_match": "yes"
      },
      "validation": {
        "identification_number": "full_match"
      }
    }
  ]
}
```

**`BIOMETRIC_NO_MATCH`**: انخفضت درجة مطابقة الوجه عن عتبة القبول، أي أن السيلفي ليس لنفس الشخص الموجود في صورة السجل.

```json 200 OK — BIOMETRIC_NO_MATCH theme={null}
{
  "request_id": "req_01H…",
  "status": "Declined",
  "issuing_state": "BRA",
  "match_type": "no_match",
  "validations": [
    {
      "outcome_code": "BIOMETRIC_NO_MATCH",
      "service_id": "bra_unico_idcloud",
      "service_name": "BRA - Unico IDCloud (CPF + selfie)",
      "source_data": {
        "identification_number": "NO_MATCH"
      },
      "validation": {
        "identification_number": "no_match"
      }
    }
  ]
}
```

**`INCONCLUSIVE`**: لم يتمكن السجل من تحديد ما إذا كان الشخص مطابقًا، فالنتيجة غير محسومة فعلًا (قد يكون الشخص موجودًا في السجل أو لا يكون). هذه ليست حالة عدم تطابق، ولا مشكلة تقنية في الصورة؛ لا يُثبت أي حقل، لذلك تكون قيمة match\_type هي null ويُرسل الفحص إلى المراجعة.

```json 200 OK — INCONCLUSIVE theme={null}
{
  "request_id": "req_01H…",
  "status": "In Review",
  "issuing_state": "BRA",
  "match_type": null,
  "validations": [
    {
      "outcome_code": "INCONCLUSIVE",
      "service_id": "bra_unico_idcloud",
      "service_name": "BRA - Unico IDCloud (CPF + selfie)",
      "source_data": {},
      "validation": {}
    }
  ]
}
```

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

تعتمد الحقول الدقيقة المعروضة في `source_data` على ما يُعيده السجل. يوثّق المثال المُولَّد للخدمة `bra_unico_idcloud` حاليًا البنية الموحّدة التالية:

* `unico_face_match`

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

تُحتسب استعلامات BRA - Unico IDCloud (CPF + صورة سيلفي) فقط عندما تتلقى Didit نتيجة حاسمة من مصدر التحقق.

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

## حول هذا المصدر

[Unico](https://unico.io) شركة برازيلية لتقنيات تحديد الهوية، وتدير أكبر سجل خاص للبيانات البيومترية للوجه في البلاد. تضم منصتها IDCloud أكثر من مليار تضمين للوجه، وتضيف نحو 35 مليون وجه جديد كل شهر، وتغذّيها تدفقات التسجيل وإعادة المصادقة لدى أكثر من 800 شركة برازيلية، بما في ذلك أربعة من أكبر خمسة بنوك في البلاد. هذا الحجم هو ما ينتج رقم التغطية المذكور أعلاه: فالاستعلام برقم CPF يُرجع سجلاً بيومترياً لنحو 96% من البالغين البرازيليين.

لدى Didit شراكة مباشرة مع Unico، لذا يمكنك الاستعلام عن IDCloud عبر واجهة برمجة تطبيقات التحقق من قواعد البيانات القياسية، بالدفع لكل استدعاء، دون عقد منفصل مع Unico، ودون حد أدنى للحجم، ودون عملية تسجيل.

**كيف يختلف هذا عن السجل الحكومي.** يقدّم Didit أيضاً [Brazil - CPF + face match (Datavalid)](https://docs.didit.me/ar/api-reference/database-validation/brazil/cpf-facial.md)، وهو المصدر الرسمي من SERPRO، وهو الخيار المناسب عندما تحتاج تحديداً إلى السجل الحكومي بوصفه مصدر الحقيقة لديك. أما IDCloud فهو الخيار الأقوى لكل ما عدا ذلك، وذلك على محورين يمكنك التحقق منهما: فهو يصل إلى نحو 96% من البالغين مقابل نحو 50% لدى Datavalid، ويطابق الوجه مع سجل بيومتري يحتفظ به السجل نفسه، لا مع صورة شخصية مأخوذة من مستند يقدّمه المستخدم، ولذلك يصمد أمام تزوير المستندات والاحتيال باستخدام CPF مسروق. وهو كذلك أقل من نصف السعر لكل استعلام.

## المسار الموصى به للبرازيل

بالنسبة لمعظم حالات الاستخدام في البرازيل لا تحتاج إلى التقاط أي مستند. يقدّم المستخدم رقم CPF، وتؤكد صورة سيلفي خضعت لكشف الحيوية أنه الشخص صاحب هذا الرقم.

**1. جمع رقم CPF**

مدخلك النصي الوحيد هو رقم CPF المكوّن من 11 رقماً، ولا صورة مستند ولا اسم ولا تاريخ ميلاد يُكتبان يدوياً.

بما أنه لا تُقرأ أي وثيقة في هذا المسار، فلن تجد Didit مصدراً تستخرج منه رقم CPF ما لم تحدد أنت ذلك. أرسله في `metadata` الخاصة بالجلسة عند إنشائها، واربطه بوصفه الإدخال `tax_number` لخطوة التحقق من قاعدة البيانات. في Business Console يتم ذلك من ربط الإدخالات الخاص بالخطوة، وعبر واجهة API لسير العمل يتم ذلك من خلال `database_validation_field_sources` في العقدة:

```json theme={null}
{
  "database_validation_countries": {"BRA": {"services": ["bra_unico_idcloud"]}},
  "database_validation_field_sources": {
    "tax_number": {"source": "expected_data", "key": "metadata.cpf"}
  }
}
```

ثم أنشئ كل جلسة مع القيمة تحت هذا المفتاح:

```json theme={null}
{"workflow_id": "<workflow_id>", "metadata": {"cpf": "12345678909"}}
```

من دون هذا الربط تُنفَّذ الخطوة، لكنها تُبلغ أن `tax_number` مفقود ولا تستعلم السجل أبداً. لا يُحتسب أي رسم في هذه الحالة، ويحمل الإدخال `database_validations` الخاص بالجلسة سبب ذلك.

**2. التقاط صورة السيلفي مع كشف الحيوية**

أضف خطوة [كشف الحيوية](https://docs.didit.me/ar/core-technology/liveness/overview.md) إلى سير العمل نفسه، واختر الطريقة التي تناسب مستوى المخاطر لديك: **كشف الحيوية السلبي** (من دون أي إجراء من المستخدم)، أو **فلاش ثلاثي الأبعاد**، أو **إجراء ثلاثي الأبعاد وفلاش** (وهما طريقتان نشطتان تعرضان أنماطاً ضوئية، وتضيف الأخيرة إجراءً عشوائياً). اضبطها عبر `face_liveness_method` (`PASSIVE` أو `FLASHING` أو `ACTIVE_3D`) في Business Console أو عبر واجهة API لسير العمل. أياً كانت الطريقة، تعرض Didit خطوة الالتقاط وتتحقق من أن الشخص حقيقي وحاضر أمام الكاميرا، وهذا ما يمنع إرسال صورة مخزنة أو إعادة عرض عبر شاشة.

**3. التحقق من رقم CPF وصورة السيلفي مقابل Unico IDCloud**

داخل مسار الجلسة تعيد Didit استخدام صورة السيلفي الخاصة بكشف الحيوية تلقائياً، فلا تتعامل أنت مع الصورة أبداً، وتقرأ رقم CPF من الربط المذكور أعلاه. ثم يتحقق IDCloud مما إذا كان هذا الوجه يعود إلى الشخص صاحب رقم CPF. تحتاج الخطوة إلى هذين المدخلين فقط. وإذا أرسلت أيضاً `full_name` أو `date_of_birth` في `metadata` وربطتهما، فسيُمرَّران إلى Unico بوصفهما تحققاً متقاطعاً، لكنهما غير مطلوبين.

> [!NOTE]
>
> ينطبق مسار رقم CPF وحده على تكاملات **الجلسات وسير العمل**، حيث تتولى Didit الالتقاط وتمرر صورة السيلفي الخاصة بكشف الحيوية إلى هذه الخدمة نيابة عنك. أما إذا استدعيت `POST /v3/database-validation/` **مباشرةً**، فإن `selfie` مدخل ملف مطلوب، وأنت من يوفر الصورة بنفسك. راجع [نظرة عامة على التحقق من قاعدة البيانات](https://docs.didit.me/ar/core-technology/database-validation/overview.md) لمعرفة الوضعين.

**التكلفة:** نحو \$0.30 لكل مستخدم تم التحقق منه باستخدام كشف الحيوية السلبي، أي \$0.20 لاستعلام IDCloud و\$0.10 لفحص الحيوية، أو نحو \$0.35 مع طريقة نشطة، حيث يكلف فحص الحيوية \$0.15. هذه أسعار القائمة، ويُطبَّق خصم خطتك على كل واحد منها. راجع [الأسعار](https://docs.didit.me/ar/getting-started/pricing.md).

**بديل لنحو 4% من الحالات التي لا تشملها التغطية.** عندما يعيد IDCloud القيمة `INCONCLUSIVE`، فهذا يعني أن السجل لم يتمكن من ربط رقم CPF بسجل بيومتري قابل للاستخدام، وغالباً لأن الشخص غير موجود فيه. تعامل مع هذه النتيجة بوصفها "لا توجد إجابة" لا بوصفها فحصاً فاشلاً، وانتقل إلى [التحقق من الهوية](https://docs.didit.me/ar/core-technology/id-verification/overview.md) الكامل: التقاط المستند ومطابقة الوجه مع صورة المستند. يبقى الجميع قابلين للتحقق، ولا تدفع رسوم التحقق من المستند إلا عن النسبة الصغيرة المتبقية.

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

**المستخدمون العائدون.** لا تحتاج إلى الدفع مقابل الاستعلام في السجل إلا مرة واحدة. بعد أن يجتاز المستخدم هذا المسار، تُخزَّن صورة السيلفي الخاصة بكشف الحيوية مقابل `vendor_data` الخاصة به، فيمكنك إعادة التحقق منه لاحقاً عبر [المصادقة البيومترية](https://docs.didit.me/ar/core-technology/biometric-auth/overview.md)، أي كشف الحيوية مع مطابقة الوجه مقابل الوجه المخزَّن، بسعر \$0.10 ومع الاختيار نفسه من طرق كشف الحيوية. لاحظ أن هذا الخيار مخصص للمستخدمين **العائدين** تحديداً، فجلسة المصادقة البيومترية تحتاج إلى وجه مخزَّن (أو إلى `portrait_image` تقدمه أنت)، وتفشل عند الإنشاء إذا لم يتوفر أيٌّ منهما. لذلك يمر المستخدمون الجدد بالمسار الموضح أعلاه أولاً.

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

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