واجهة إنشاء إدخال القائمة API: قائمة الحظر وقائمة السماح

curl

curl -X POST 'https://verification.didit.me/v3/lists/11111111-2222-3333-4444-555555555555/entries/' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"value": "+14155552671", "comment": "Reported fraud"}'

from didit import Didit

# Reads DIDIT_API_KEY.
client = Didit()

result = client.lists.entries.create(
    "11111111-2222-3333-4444-555555555555",
    value="+14155552671",
    comment="Reported fraud",
)
print(result)

import Didit from "@didit-protocol/sdk-node";

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

const result = await didit.lists.entries.create("11111111-2222-3333-4444-555555555555", {
  value: "+14155552671",
  comment: "Reported fraud",
});
console.log(result);

ctx := context.Background()
// Reads DIDIT_API_KEY.
client := didit.NewClient()

result, err := client.Lists.Entries.Create(ctx, "11111111-2222-3333-4444-555555555555", didit.ListsEntriesCreateParams{
	Value:   didit.String("+14155552671"),
	Comment: didit.String("Reported fraud"),
})
if err != nil {
	log.Fatal(err)
}
fmt.Printf("%+v\n", result)

import me.didit.Didit;
import me.didit.types.ListsEntriesCreateParams;

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

var result = client.lists().entries().create("11111111-2222-3333-4444-555555555555", ListsEntriesCreateParams.builder()
        .value("+14155552671")
        .comment("Reported fraud")
        .build());
System.out.println(result);

<?php

require 'vendor/autoload.php';

use Didit\DiditClient;

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

$result = $didit->lists->entries->create('11111111-2222-3333-4444-555555555555', [
    'value' => '+14155552671',
    'comment' => 'Reported fraud',
]);
print_r($result->toArray());

require "didit"

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

result = didit.lists.entries.create(
  "11111111-2222-3333-4444-555555555555",
  value: "+14155552671",
  comment: "Reported fraud"
)
puts result.to_h

using System;
using System.Text.Json;
using Didit;

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

var result = await client.Lists.Entries.CreateAsync("11111111-2222-3333-4444-555555555555", new ListsEntriesCreateParams
{
    Value = "+14155552671",
    Comment = "Reported fraud",
});
Console.WriteLine(JsonSerializer.Serialize(result));

{
  "uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "value": "+14155552671",
  "display_label": "",
  "comment": "Reported fraud",
  "added_by": "api",
  "reference_session_id": null,
  "reference_session_number": null,
  "reference_session_type": null,
  "reference_object_uuid": null,
  "metadata": null,
  "created_at": "2026-10-12T10:04:51.220391Z"
}

POST

lists

{list_uuid}

entries

curl

curl -X POST 'https://verification.didit.me/v3/lists/11111111-2222-3333-4444-555555555555/entries/' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"value": "+14155552671", "comment": "Reported fraud"}'

from didit import Didit

# Reads DIDIT_API_KEY.
client = Didit()

result = client.lists.entries.create(
    "11111111-2222-3333-4444-555555555555",
    value="+14155552671",
    comment="Reported fraud",
)
print(result)

import Didit from "@didit-protocol/sdk-node";

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

const result = await didit.lists.entries.create("11111111-2222-3333-4444-555555555555", {
  value: "+14155552671",
  comment: "Reported fraud",
});
console.log(result);

ctx := context.Background()
// Reads DIDIT_API_KEY.
client := didit.NewClient()

result, err := client.Lists.Entries.Create(ctx, "11111111-2222-3333-4444-555555555555", didit.ListsEntriesCreateParams{
	Value:   didit.String("+14155552671"),
	Comment: didit.String("Reported fraud"),
})
if err != nil {
	log.Fatal(err)
}
fmt.Printf("%+v\n", result)

import me.didit.Didit;
import me.didit.types.ListsEntriesCreateParams;

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

var result = client.lists().entries().create("11111111-2222-3333-4444-555555555555", ListsEntriesCreateParams.builder()
        .value("+14155552671")
        .comment("Reported fraud")
        .build());
System.out.println(result);

<?php

require 'vendor/autoload.php';

use Didit\DiditClient;

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

$result = $didit->lists->entries->create('11111111-2222-3333-4444-555555555555', [
    'value' => '+14155552671',
    'comment' => 'Reported fraud',
]);
print_r($result->toArray());

require "didit"

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

result = didit.lists.entries.create(
  "11111111-2222-3333-4444-555555555555",
  value: "+14155552671",
  comment: "Reported fraud"
)
puts result.to_h

using System;
using System.Text.Json;
using Didit;

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

var result = await client.Lists.Entries.CreateAsync("11111111-2222-3333-4444-555555555555", new ListsEntriesCreateParams
{
    Value = "+14155552671",
    Comment = "Reported fraud",
});
Console.WriteLine(JsonSerializer.Serialize(result));

{
  "uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "value": "+14155552671",
  "display_label": "",
  "comment": "Reported fraud",
  "added_by": "api",
  "reference_session_id": null,
  "reference_session_number": null,
  "reference_session_type": null,
  "reference_object_uuid": null,
  "metadata": null,
  "created_at": "2026-10-12T10:04:51.220391Z"
}

أضف إدخالاً إلى قائمة. تُتحقق القيمة وفق نوع إدخال القائمة:

email: عنوان بريد إلكتروني صالح
phone: رقم هاتف دولي صالح، يُخزَّن بصيغة E.164 (مثل +14155552671)
ip_address: عنوان IP صالح أو نطاق CIDR (مثل 192.168.1.1 أو 10.0.0.0/8)
device_fingerprint: ما لا يقل عن 8 أحرف من بين الحروف والأرقام و- و_ و: و.. ترفض قائمة الحظر بصمةً أبلغت عنها عدة أجهزة مختلفة، لأن حظرها سيرفض أشخاصاً لا علاقة لهم بالأمر.
country: رمز الدولة وفق ISO 3166-1 alpha-3 صالح (مثل USA وGBR وESP). تُقبل رموز alpha-2 (مثل US) وتُحوَّل تلقائياً إلى alpha-3.
user، business: القيمة vendor_data الخاصة بالمستخدم أو الشركة
face، document، wallet_address، bank_account، key: أي سلسلة نصية غير فارغة

جميع قيم الإدخال غير حساسة لحالة الأحرف. تُوحَّد القيم التي ترسلها عند التخزين (أرقام الهواتف إلى E.164، ورموز الدول إلى أحرف كبيرة، وكل ما عداها إلى أحرف صغيرة)، وتُطابَق دون تمييز لحالة الأحرف أثناء التحقق. مثلاً، حظر User@Example.COM سيلتقط أيضاً user@example.com. تحتوي القائمة على كل قيمة مرة واحدة فقط، وإضافة قيمة موجودة في القائمة تُرجع 400.

بالنسبة إلى الوجه، استخدم رفع الوجه عندما تملك صورة فقط، أو أرسل reference_session_id لأخذ وجه من جلسة موجودة. يحتاج إدخال الوجه إلى وجه مخزَّن للمطابقة معه، ولا توفر ذلك القيمةُ value المكتوبة يدوياً.

الإضافة من جلسة

عندما تُرسل reference_session_id، يقوم Didit بما يلي:

يبحث عن الجلسة (ويجب أن تنتمي إلى التطبيق نفسه)
يقرأ القيمة من أحدث سجل في الجلسة من نوع إدخال القائمة:
- face: وجه صورة السيلفي الخاصة بكشف الحيوية؛ والقيمة value هي معرّف UUID للوجه
- document: رقم المستند؛ ويُخزَّن الاسم الكامل والولاية المُصدِرة ونوع المستند والمنطقة ورقم المستند في metadata، ويكون display_label افتراضياً اسم صاحب المستند ورقم المستند
- phone: رقم الهاتف
- email: عنوان البريد الإلكتروني
- ip_address: عنوان IP الخاص بالجلسة
- device_fingerprint: بصمة تُعرّف جهازاً واحداً، مع تفضيل جهاز أكمل خطوة تحقق. في قائمة الحظر، يرفض Didit الجلسة التي تحتوي فقط على بصمة من نوع الجهاز، أو التي اكتملت على أكثر من جهاز واحد. في هذه الحالة أرسل البصمة الدقيقة بوصفها value.
يربط الإدخال بالجلسة (reference_session_id) وبالسجل (reference_object_uuid) لتتبع المصدر

في قوائم الحظر الخاصة بالوجه والمستند والهاتف والبريد الإلكتروني على مستوى النظام، يُوسَم السجل أيضاً بأنه في قائمة الحظر، فتُرفض الجلسات الجديدة المطابقة له. لأي نوع إدخال آخر، أرسل value أيضاً. يُرجع 400 إذا لم يتم العثور على الجلسة، أو إذا لم تحتوِ على بيانات لنوع الإدخال المطلوب.

الوجوه من صورة السيلفي الملتقطة أثناء تصوير المستند

أثناء تصوير المستخدم لمستنده، يمكن للكاميرا الأمامية التقاط صورة سيلفي له (الصورتان front_image_camera_front وback_image_camera_front من تقرير التحقق من الهوية). يمكن إضافة هذا الوجه إلى قائمة حظر الوجوه إلى جانب وجه كشف الحيوية، وذلك بتمرير face_image_source مع الصورة التي تريدها.

{
  "reference_session_id": "33333333-4444-5555-6666-777777777777",
  "face_image_source": "front_image_camera_front"
}

يُنشأ الإدخال فقط في قائمة حظر الوجوه على مستوى النظام، ويجب ترك value فارغة: يأخذ Didit الوجه من صورة السيلفي في الجلسة.
يجب أن تحتوي صورة السيلفي على وجه واحد واضح. إن لم تكن كذلك، يُرجع الطلب 400 ولا يُضاف شيء.
يمكن إضافة كل صورة سيلفي مرة واحدة فقط. يوضح metadata.face_image_source وmetadata.reference_node_id أي صورة سيلفي جاء منها الإدخال.
في سير عمل فيه أكثر من خطوة تحقق من الهوية، يحدد reference_node_id الخطوة التي ستُستخدم صورة السيلفي الخاصة بها. افتراضياً، يستخدم Didit أحدث تحقق من الهوية يحتوي على تلك الصورة.
من تلك اللحظة يُفحص الوجه كأي وجه محظور آخر: مقابل صورة السيلفي الخاصة بكشف الحيوية في كل جلسة جديدة، ومقابل كل صورة سيلفي جديدة من تصوير المستند (انظر FRONT_CAMERA_FACE_IN_BLOCKLIST).
حذف الإدخال يزيل الوجه من قائمة الحظر، ويتوقف عن مطابقة الجلسات الجديدة.

جلسات تحتوي على عدة سجلات من النوع نفسه

قد تحتوي الجلسة على أكثر من سجل من النوع نفسه، مثل رقمي هاتف في سير عمل متعدد الخطوات. يقرأ Didit دائماً الأحدث. إذا أرسلت value مع reference_session_id، يخزّن الإدخال القيمة value التي أرسلتها، لكنه يظل مرتبطاً بالسجل الأحدث، وفي قائمة حظر على مستوى النظام يكون هذا السجل هو المُعلَّم. لإضافة قيمة من سجل أقدم، أضفها باستخدام value وحدها دون reference_session_id:

{
  "value": "+34612345678",
  "comment": "First phone number of session 42"
}

الإشارة إلى المعاملات والمستخدمين والشركات

عند حظر بيانات من معاملة أو من مستخدم أو شركة لدى البائع، مرّر معرّف UUID الخاص بالكيان في reference_object_uuid، وحدد نوع المصدر في metadata:

{
  "value": "0x52908400098527886E0F7030069857D2E4169EE7",
  "reference_object_uuid": "55555555-6666-7777-8888-999999999999",
  "metadata": {
    "reference_type": "transaction",
    "reference_id": "55555555-6666-7777-8888-999999999999"
  }
}

يتيح لك ذلك الانتقال من إدخال قائمة الحظر إلى المعاملة أو المستخدم أو الشركة الأصلية في وحدة التحكم. يحفظ Didit مفاتيح metadata التي ترسلها، باستثناء reference_image_url وfront_image_url، وهما مفتاحان يضبطهما Didit وحده. أما الإدخال المأخوذ من جلسة، فيضيف Didit إلى مفاتيحك مفاتيحه الخاصة، وتكون مفاتيحه هي الغالبة.

مصدر الكيان	`reference_object_uuid`	`metadata.reference_type`
جلسة التحقق	يضبطه Didit (سجل الوجه أو المستند أو الهاتف أو البريد الإلكتروني)	غير مطلوب: استخدم `reference_session_id`
معاملة	معرّف UUID للمعاملة	`"transaction"`
مستخدم لدى البائع	`didit_internal_id`	`"vendor_user"`
شركة لدى البائع	`didit_internal_id`	`"vendor_business"`

في قائمتي حظر المستخدمين والشركات على مستوى النظام، يضبط Didit أيضاً المستخدمين أو الشركات المطابقين على BLOCKED: أي الذين يساوي vendor_data لديهم القيمة value، أو الذين يساوي didit_internal_id لديهم القيمة reference_object_uuid. انظر قائمة حظر المستخدمين وقائمة حظر الشركات.

التفويضات

x-api-key

string

header

مطلوب

مفتاح API الخاص بتطبيقك، من Developers -> API keys في Business Console. يمتلك المفتاح الأساسي وصولاً كاملاً. يمكن تحديد نطاق المفتاح المسمى: لا شيء، أو قراءة، أو كتابة لكل مورد، ومحدوداً ببعض مسارات العمل أو بالجلسات المقبولة، وبقائمة من عناوين IP، وبتاريخ انتهاء الصلاحية. يشير 401 إلى أن المفتاح غير صحيح أو ملغى أو منتهي الصلاحية؛ ويشير 403 إلى أنه لم يتم إرسال أي مفتاح، أو أن المفتاح ليس لديه حق الوصول إلى هذا المورد أو الإجراء، أو أن الطلب جاء من عنوان خارج قائمة عناوين IP الخاصة به؛ ويشير 404 في مسار جلسة إلى أن الجلسة خارج مسارات العمل أو الحالات الخاصة بالمفتاح. يتلقى المفتاح الذي لا يمتلك حق الوصول إلى الوسائط عناوين URL للصور ومقاطع الفيديو وملفات PDF كـ null، ويتلقى المفتاح الذي لا يمتلك إذن كتابة للجلسات روابط الجلسة وtoken كـ null. راجع https://docs.didit.me/console/api-keys.

معلمات المسار

list_uuid

string<uuid>

مطلوب

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

الجسم

application/json

أرسل value أو reference_session_id أو كليهما. تعتمد الحقول المستخدمة على entry_type الخاص بالقائمة.

value

string

القيمة المراد إدراجها، ويتم التحقق منها وفقاً لـ entry_type الخاص بالقائمة: email عنوان بريد إلكتروني صالح؛ phone رقم دولي صالح، مخزن بتنسيق E.164؛ ip_address عنوان IP أو نطاق CIDR (على سبيل المثال 10.0.0.0/8)؛ device_fingerprint 8 أحرف على الأقل من الحروف والأرقام و- و_ و: و. (ترفض قائمة الحظر البصمة التي أبلغت عنها عدة أجهزة مختلفة)؛ country رمز ISO 3166-1 alpha-2 أو alpha-3، مخزن بتنسيق alpha-3؛ user وbusiness هما vendor_data؛ وأي نوع آخر هو سلسلة نصية غير فارغة. تخزن بأحرف صغيرة باستثناء أرقام الهواتف ورموز الدول، وتحتفظ القائمة بكل قيمة مرة واحدة فقط (غير حساسة لحالة الأحرف). مطلوب ما لم يتم إرسال reference_session_id؛ ويجب تركه فارغاً عند استخدام face_image_source لالتقاط المستندات.

reference_session_id

string<uuid>

جلسة تحقق من شخص أو شركة تابعة لتطبيقك لأخذ القيمة منها. يقرأ Didit أحدث سجل للجلسة من نوع إدخال القائمة (face أو document أو phone أو email أو ip_address أو device_fingerprint)، ويربط الإدخال بالجلسة وبذلك السجل، ويملأ display_label و metadata للمستندات. بالنسبة لقائمة حظر device_fingerprint، يتم رفض الجلسة التي تحتوي فقط على بصمة فئة الجهاز أو التي اكتملت على أكثر من جهاز واحد: أرسل البصمة الدقيقة كـ value. بالنسبة لأنواع الإدخال الأخرى، أو عندما لا تحتوي الجلسة على مثل هذا السجل، أرسل value أيضاً؛ ويتم بعد ذلك تخزين value الخاصة بك مع استمرار ربط الإدخال بالجلسة.

reference_object_uuid

string<uuid>

معرّف UUID للسجل الذي يمثله الإدخال عندما لا يأتي من جلسة: معرّف UUID للمعاملة، أو didit_internal_id لمستخدم أو شركة. قم بإقرانه مع metadata.reference_type. يُستبدل بسجل الجلسة عندما يوفره reference_session_id.

face_image_source

enum<string>

افتراضي:liveness

قوائم الوجوه التي تحتوي على reference_session_id: تحدد الصورة التي تم أخذ الوجه منها من صور الجلسة. القيمة liveness (الافتراضية) هي صورة السيلفي لكشف الحيوية. والخاصيتان front_image_camera_front وback_image_camera_front هما صورتا السيلفي اللتان التقطتهما الكاميرا الأمامية أثناء تصوير المستخدم للوجه الأمامي أو الخلفي لمستنده: تُقبلان فقط في قائمة حظر الوجوه الخاصة بالنظام، مع reference_session_id وقيمة value فارغة. يمكن إضافة كل صورة سيلفي مرة واحدة ويجب أن تُظهر وجهاً واحداً واضحاً.

الخيارات المتاحة:

liveness,

front_image_camera_front,

back_image_camera_front

reference_node_id

string | null

مع face_image_source لالتقاط المستند: عقدة التحقق من الهوية التي تُستخدم صورتها السيلفي، في مسارات سير العمل التي تحتوي على أكثر من عقدة. القيمة الافتراضية هي أحدث عملية تحقق من الهوية تحتوي على تلك الصورة. يُرفض استخدامه مع liveness.

Maximum string length: 100

display_label

string

تسمية سهلة القراءة. عندما تكون فارغة، تستنتج Didit واحدة من الجلسة متى أمكنها ذلك (على سبيل المثال اسم حامل المستند ورقمه).

Maximum string length: 512

comment

string

ملاحظة بنص حر، مثل سبب الإدراج في القائمة.

metadata

object

كائن JSON بصيغة حرة يُخزن مع القيد ويُعاد كما تم تخزينه. استخدم reference_type و reference_id لتربط لوحة التحكم بالمصدر. يتم تعيين reference_image_url و front_image_url بواسطة Didit فقط ويتم تجاهلهما إذا أرسلتهما. بالنسبة لقيد تمت قراءته من جلسة، يتم دمج مفاتيح Didit مع مفاتيحك.

Show child attributes

الاستجابة

تم إنشاء الإدخال.

قيمة واحدة في قائمة.

uuid

string<uuid>

مطلوب

معرّف المُدخل. استخدمه كـ entry_uuid في حذف مُدخل من قائمة.

value

string

مطلوب

القيمة المدرجة: رقم هاتف بصيغة E.164، أو عنوان بريد إلكتروني، أو رقم مستند، أو عنوان IP أو نطاق CIDR، أو بصمة جهاز، أو عنوان محفظة، أو حساب مصرفي، أو رمز دولة وفق معيار ISO 3166-1 alpha-3، أو vendor_data، أو أي سلسلة نصية في قائمة key، أو UUID للوجه المخزن في قائمة الوجوه. تُخزن القيم التي ترسلها بأحرف صغيرة، باستثناء أرقام الهواتف ورموز الدول. مطابقة النصوص غير حساسة لحالة الأحرف.

display_label

string | null

مطلوب

تسمية سهلة القراءة. تملؤها Didit للإدخالات المأخوذة من جلسة (على سبيل المثال اسم حامل المستند ورقمه) إذا لم ترسل أياً منها.

Maximum string length: 512

comment

string

مطلوب

ملاحظة بنص حر. سلسلة فارغة عند عدم التعيين.

added_by

string | null

مطلوب

من أضاف الإدخال: api (مفتاح API)، أو عنوان البريد الإلكتروني لمستخدم لوحة التحكم أو console، أو system أو migration (إدخالات أنشأتها Didit)، أو rule (إجراء قاعدة معاملات أو قاعدة مراقبة).

reference_session_id

string<uuid> | null

مطلوب

جلسة التحقق التي تم أخذ الإدخال منها. null عندما تتم إضافة الإدخال حسب القيمة.

reference_session_number

integer | null

مطلوب

رقم لتلك الجلسة بنطاق التطبيق، كما يظهر في وحدة التحكم.

reference_session_type

enum<string> | null

مطلوب

kyc لجلسة التحقق من شخص، وkyb لجلسة التحقق من شركة، وnull عندما لا توجد جلسة.

الخيارات المتاحة:

kyc,

kyb,

null

reference_object_uuid

string<uuid> | null

مطلوب

السجل الذي يمثله الإدخال: سجل الوجه، أو المستند، أو الهاتف، أو البريد الإلكتروني المقروء من الجلسة، أو الوجه الذي تم إنشاؤه عبر تحميل وجه إلى قائمة، أو UUID الذي أرسلته (على سبيل المثال UUID لمعاملة أو didit_internal_id الخاص بالمستخدم).

metadata

object | null

مطلوب

سياق إضافي. يحتوي على المفاتيح التي تعينها Didit (المدرجة هنا) مدمجة مع أي metadata أرسلتها عند إنشاء الإدخال، وتُعاد كما تم تخزينها. ويكون null عند عدم وجود أي منها.

Show child attributes

created_at

string<date-time>

مطلوب

وقت إضافة المُدخل.

آخر تعديل في ٧ نوفمبر ٢٠٢٦

​الإضافة من جلسة

​الوجوه من صورة السيلفي الملتقطة أثناء تصوير المستند

​جلسات تحتوي على عدة سجلات من النوع نفسه

​الإشارة إلى المعاملات والمستخدمين والشركات

التفويضات

معلمات المسار

الجسم

الاستجابة

الإضافة من جلسة

الوجوه من صورة السيلفي الملتقطة أثناء تصوير المستند

جلسات تحتوي على عدة سجلات من النوع نفسه

الإشارة إلى المعاملات والمستخدمين والشركات