للمطورين
مرجع الواجهة البرمجية
الإصدار 1 · العنوان الأساسي https://api.lumex.id/v1
- البداية السريعة
- المصادقة
- إنشاء عملية تحقق
- علامتك في الصفحة
- بطاقات الهوية من أي بلد
- الحد الأدنى للعمر
- الجهاز والاتصال
- درجة المخاطر
- جلب عملية تحقق
- كائن التحقق
- المراجعة اليدوية
- البطاقات المكررة
- الوجه نفسه ببطاقات مختلفة
- نسخ الوثائق
- الإشعارات
- الأخطاء
البداية السريعة
- أنشئ عملية تحقق من خادمك لأحد مستخدميك.
- أرسل المستخدم إلى الرابط
urlفي الرد. يصور بطاقة هويته أو جواز سفره ويلتقط صورة شخصية قصيرة من متصفح هاتفه. - نرسل النتيجة إلى عنوان الإشعارات لديك، ونعيد المستخدم إلى
redirect_url.
جميع الطلبات والردود بصيغة JSON. استدع الواجهة من خادمك فقط، وليس من المتصفح أو تطبيق الجوال، لأن مفتاحك السري يجب أن يبقى سريا.
المصادقة
أرسل مفتاحك السري في الترويسة Authorization. تحصل على مفتاحين في لوحة التحكم:
| المفتاح | الاستخدام |
|---|---|
lx_test_… | وضع التجربة. يشغل الخطوات كاملة مع شريط يوضح أنها تجربة. بلا رسوم. حتى 100 عملية تجريبية خلال 24 ساعة. |
lx_live_… | الوضع الفعلي. تحقق حقيقي، يخصم من العمليات المشمولة أو من رصيدك المسبق. |
Authorization: Bearer lx_live_…
إنشاء عملية تحقق
| الحقل | النوع | الوصف |
|---|---|---|
reference | نص، إلزامي | معرف المستخدم لديك، حتى 100 حرف. يعود في كل رد وإشعار. |
document | نص | id_card أو passport أو any. إذا لم ترسله يطبق إعداد الوثائق المقبولة في لوحة التحكم (قسم المطورين)، وقيمته الأولى any أي يختار المستخدم. |
id_countries | قائمة نصوص | اقبل بطاقات الهوية من هذه الدول فقط، برموزها المكونة من ثلاثة أحرف كما تطبع في السطور المرمزة، مثل ["KWT", "FRA"]. حتى 60 دولة. القيمة null أو [] تقبل بطاقة الهوية من أي بلد. إذا لم ترسله يطبق إعداد بطاقات الهوية من في لوحة التحكم (قسم المطورين)، وقيمته الأولى أي بلد. انظر بطاقات الهوية من أي بلد. |
min_age | رقم صحيح | الحد الأدنى للعمر في هذه العملية، رقم صحيح من 13 إلى 99. يرفض من كان أصغر من ذلك. القيمة 0 تلغي التحقق من العمر في هذه العملية. إذا لم ترسله يطبق إعداد الحد الأدنى للعمر في لوحة التحكم (قسم المطورين)، وهو غير مفعل في البداية. انظر الحد الأدنى للعمر. |
locale | نص | en أو ar. الافتراضي en، ويمكن للمستخدم تغيير اللغة أثناء الخطوات. |
redirect_url | نص | عنوان HTTPS يعود إليه المستخدم عند الانتهاء. نضيف إليه ?verification=vrf_…. |
metadata | كائن | حتى 20 مفتاحا وقيمة نصية خاصة بك، تعود كما أرسلتها. |
أرسل الترويسة Idempotency-Key بقيمة فريدة لتكون إعادة المحاولة آمنة. استخدام المفتاح نفسه خلال 24 ساعة يعيد النتيجة الأولى بدل إنشاء عملية ثانية. مفاتيح التجربة والمفاتيح الفعلية منفصلة.
curl https://api.lumex.id/v1/verifications \ -H "Authorization: Bearer lx_live_…" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: 6f1c2b7e-signup-1042" \ -d '{ "reference": "user_1042", "document": "any", "locale": "ar", "redirect_url": "https://your-site.com/verified" }'
الرد 201 Created:
{
"id": "vrf_7KQ2M9",
"reference": "user_1042",
"status": "created",
"url": "https://verify.lumex.id/v/…",
"expires_at": "2026-10-09T08:00:00Z",
"created_at": "2026-10-08T08:00:00Z"
}يعمل الرابط لمدة 24 ساعة ولشخص واحد فقط. أنشئ عملية جديدة إذا انتهت صلاحيته.
علامتك في صفحة التحقق
يرى الأشخاص نشاطك التجاري في صفحة لومكس قبل أن يبدأوا. اضبط ذلك مرة واحدة من لوحة التحكم في app.lumex.id.
- اسم النشاط التجاري بالإنجليزية وبالعربية (الإعدادات). املأ اسما واحدا على الأقل. تعرض الصفحة الاسم بلغتها: الاسم العربي في الصفحات العربية والاسم الإنجليزي في الصفحات الإنجليزية، واللغة التي تترك فارغة لا يظهر فيها اسم. أرسل
localeمع كل عملية تحقق ليرى الأشخاص الاسم الصحيح. - الشعار (الإعدادات). PNG أو JPG أو SVG، بحد أقصى 500 كيلوبايت. يفضل أن يكون مربعا ليملأ الإطار بجانب اسمك، في كل الخطط. وفي خطة العلامة الخاصة يحل أيضا محل علامة لومكس.
- الوثائق المقبولة (المطورون). بطاقة الهوية أو جواز السفر (يختار الشخص)، أو بطاقة الهوية فقط، أو جواز السفر فقط. الحقل
documentفي عملية التحقق يتقدم على هذا الإعداد. - بطاقات الهوية من (المطورون). أي بلد، أو الدول التي تختارها فقط. وتذكر الصفحة بطاقات هذه الدول فقط. الحقل
id_countriesفي عملية التحقق يتقدم على هذا الإعداد. - الحد الأدنى للعمر (المطورون). بدون تحقق من العمر، أو 18 سنة أو أكثر، أو عمر آخر من 13 إلى 99. الحقل
min_ageفي عملية التحقق يتقدم على هذا الإعداد.
بطاقات الهوية من أي بلد
يقرأ لومكس بطاقة الهوية الوطنية من أي بلد، بالطريقة نفسها التي يقرأ بها جوازات السفر: من السطور المرمزة في الوجه الخلفي للبطاقة. وتحملها معظم بطاقات الهوية الوطنية، ومنها بطاقات معظم دول أوروبا وبطاقات مواطني دول الخليج.
- دولة البطاقة هي الدولة المطبوعة في سطورها المرمزة، وليست موقع الزائر أبدا. عند اختيار هذه الدول فقط، تظهر لبطاقة أي دولة أخرى رسالة «هذه البطاقة غير مقبولة هنا»، ويمكن للشخص مسح بطاقة أخرى أو استخدام جواز سفره، دون أي رسوم.
- تذكر صفحة التحقق ما تقبله فقط: «بطاقة هويتك الوطنية» عند قبول أي بلد، وأسماء الدول عند تحديد قائمة، واسم البطاقة نفسها عند تحديد دولة واحدة، مثل «البطاقة المدنية الكويتية».
- قبل أي تصوير، تعرض الصفحة مربع قبل التصوير بنصائح قصيرة: إضاءة معتدلة بعيدا عن الضوء المباشر، وسطح داكن ومستو، وإمالة البطاقة قليلا لتجنب اللمعان، وظهور البطاقة كاملة داخل الإطار. ويظهر تحت رمز QR على الكمبيوتر، وفي الشاشة الأولى على الهاتف، بلغة الصفحة، وبصيغة البطاقة أو الجواز أو كليهما، دون أي إعداد.
- البطاقات التي لا تحمل سطورا مرمزة في وجهها الخلفي، مثل رخص القيادة الأمريكية وبطاقات الإقامة السعودية وبطاقة آدهار الهندية، لا يمكن قراءتها. وبعد عدة محاولات يبلغ الشخص بذلك ويعرض عليه استخدام جواز سفره.
- دولة البطاقة المستخدمة في الحقل
document.country. والقائمة التي طبقت على العملية في الحقلid_countries، أوnullعند قبول أي بلد. - تعطي كل بطاقة البيانات الموجودة في سطورها المرمزة. وتعطي البطاقة المدنية الكويتية أيضا الاسم الإنجليزي الكامل والاسم العربي والعنوان وفصيلة الدم. وتعطي بطاقة الهوية الإماراتية أيضا رقم الهوية المكون من 15 رقما في الحقل
personal_number.
الحد الأدنى للعمر
حدد حدا أدنى للعمر، وسيرفض لومكس كل من هو أصغر منه، بناء على تاريخ الميلاد في السطور المرمزة للوثيقة. تكون هذه السطور قد اجتازت أرقام التحقق الخاصة بها، وفي البطاقة المدنية الكويتية يجب أن يطابق تاريخ الميلاد الرقم المدني أيضا. يحسب العمر بتاريخ اليوم بالتوقيت العالمي المنسق. لا يطلب من الشخص أي شيء إضافي، ولا توجد رسوم إضافية.
- تخبر شاشة البداية الشخص بالحد الأدنى للعمر، مثل «يجب أن يكون عمرك 18 سنة أو أكثر».
- يوقف من كان أصغر سنا مباشرة بعد مسح الوثيقة، قبل التقاط أي صورة شخصية. ترفض العملية بالسبب
under_minimum_ageوتحتسب مثل أي عملية مرفوضة، ولا تحفظ أي نسخة من الوثيقة. - الوثيقة التي لا تحمل تاريخ ميلاد كاملا (بعض جوازات السفر لا تذكر اليوم أو الشهر) ترفض بالسبب
birth_date_unknown. وعند تفعيل أرسلها لي للمراجعة تنتظرك بالحالةin_reviewبالسببbirth_date_unknownبدلا من ذلك. - تحمل العملية التي فيها تحقق من العمر الحقلين
min_ageوchecks.age، وقيمته"passed"أو"failed"أو"review". ومن دونه تكون قيمةmin_ageهيnullولا يوجدchecks.age.
{
"status": "declined",
"decline_reasons": ["under_minimum_age"],
"min_age": 18,
"checks": { "code_lines": "passed", "expiry": "passed", "age": "failed" }
}الجهاز والاتصال
أثناء المسح، يفحص لومكس أيضا الهاتف والاتصال بالإنترنت. ويكشف ذلك ما لا تكشفه الوثيقة والصورة الشخصية: تطبيق كاميرا يمرر مقطع فيديو، أو متصفح يدار ببرنامج آلي، أو هاتف واحد خلف عدة مستخدمين. لا يطلب من الشخص أي شيء إضافي، ولا توجد رسوم إضافية. ولا يوجد إعداد خاص: يتبع اختيارك في عمليات التحقق غير الواضحة.
| المؤشر | المراجعة غير مفعلة | المراجعة مفعلة |
|---|---|---|
| تطبيق كاميرا (مثل OBS أو ManyCam) أو متصفح يدار ببرنامج آلي | ترفض بالسبب device_tampering | in_review بالسبب device_tampering |
| استخدام الهاتف نفسه لثلاثة مستخدمين آخرين أو أكثر في حسابك خلال 24 ساعة | يبلغ عنه | in_review بالسبب repeat_device |
| الاتصال نفسه خلف ثلاثة مستخدمين آخرين أو أكثر، أو شبكة VPN أو مركز بيانات، أو بلد اتصال يختلف عن بلد الوثيقة | يبلغ عنه فقط ولا يرفض أبدا | |
- قيمة
checks.deviceهي"passed"أو"flagged"(أمر يستحق المعرفة) أو"review"أو"failed"(تطبيق كاميرا أو متصفح آلي). - يحمل الحقل
deviceالتفاصيل:osوbrowser، وip_country(رمز من ثلاثة أحرف مثل رمز الوثيقة)، وnetwork("isp"أو"hosting")، وnetwork_name، وvpn_suspected، وvirtual_camera، وautomation، وsame_device_24hوsame_network_24h(المستخدمون الآخرون في حسابك خلال آخر 24 ساعة). وقيمتهnullلعمليات التحقق التي سبقت هذه الفحوص. - لا يخزن عنوان الإنترنت نفسه ولا يعاد أبدا، بل يحفظ كبصمة أحادية الاتجاه تختلف لكل جهة، وتمسح بعد 24 ساعة.
درجة المخاطر
تحصل كل عملية تحقق تصل إلى الصورة الشخصية على درجة مخاطر من 0 إلى 100. تجمع الدرجة مؤشرات تحذيرية يفحصها لومكس بالفعل، لترى بنظرة واحدة أي العمليات الناجحة تستحق نظرة ثانية. وتبقى حالات الفشل الواضحة مرفوضة كما كانت، ولا توجد رسوم إضافية.
| المؤشر | الرمز | النقاط |
|---|---|---|
| تطبيق كاميرا أو متصفح آلي | device_tampering | 60 |
| الوجه نفسه لمستخدم آخر ببطاقة مختلفة | same_face | 40 |
| قد تكون صورة لشاشة أو ورقة مطبوعة | spoof_suspected | 35 |
| تطابق الوجه أقل من الحد لكنه قريب منه | face_close | 30 |
| البطاقة نفسها مستخدمة لمستخدم آخر | duplicate_id | 30 |
| بيانات البطاقة غير متطابقة | details_disagree | 30 |
| الهاتف نفسه لثلاثة مستخدمين آخرين أو أكثر خلال 24 ساعة | repeat_device | 30 |
| قد تكون البطاقة نسخة مصورة | possible_photocopy | 25 |
| الاتصال نفسه لثلاثة مستخدمين آخرين أو أكثر خلال 24 ساعة | repeat_network | 15 |
| الهاتف نفسه لمستخدم أو مستخدمين آخرين خلال 24 ساعة | shared_device | 10 |
| شبكة VPN أو مركز بيانات | vpn | 10 |
| تعذرت قراءة بعض البيانات | details_unread | 10 |
| توقيت الهاتف يختلف عن توقيت الاتصال | timezone_mismatch | 5 |
تجمع النقاط بحد أقصى 100. المستويات: low أقل من 30، وmedium من 30 إلى 59، وhigh من 60. وتبقى شبكة VPN وحدها (10) أو اتصال مكتب مشترك (15) ضمن المستوى المنخفض.
يحدد إعداد الفحوصات عالية المخاطر (لوحة التحكم، المطورون) ما يحدث لعملية تبلغ درجتها 60 أو أكثر وكانت ستقبل:
- عرض الدرجة فقط (الافتراضي): لا يتغير شيء.
- إرسالها للمراجعة: تنتقل العملية إلى
in_reviewبالسببhigh_risk. ويتطلب ذلك ضبط عمليات التحقق غير الواضحة على المراجعة. - رفضها: ترفض العملية بالسبب
high_risk. ويطلب من الشخص التواصل مع موقعك، ولا يرى الدرجة أبدا.
يحمل الحقل risk القيم score وlevel وsignals (الرموز أعلاه، الأقوى أولا). وقيمته null حتى تنتهي خطوة الصورة الشخصية، وللعمليات التي توقفت قبلها (مثل التحقق من العمر)، وللعمليات التي سبقت درجة المخاطر.
جلب عملية تحقق
يعيد كائن التحقق كاملا. استخدمه للتأكد من إشعار وصلك، أو للاستعلام الدوري إذا لم تتمكن من استقبال الإشعارات.
curl https://api.lumex.id/v1/verifications/vrf_7KQ2M9 \
-H "Authorization: Bearer lx_live_…"كائن التحقق
{
"id": "vrf_7KQ2M9",
"reference": "user_1042",
"status": "approved",
"decline_reasons": [],
"min_age": 18,
"id_countries": null,
"document": {
"type": "id_card",
"country": "KWT",
"number": "0123456789",
"surname": "ALSALEM",
"given_names": "FAHAD",
"nationality": "KWT",
"birth_date": "1987-04-15",
"sex": "M",
"expiry_date": "2029-03-01",
"personal_number": "287041501208",
"name_ar": "فهد السالم",
"name_en": "FAHAD ABDULLAH ALSALEM",
"blood_group": "O+",
"address": {
"area": "الجابرية",
"block": "7",
"street": "15",
"avenue": null,
"building": "22",
"floor": "3",
"unit_type": "شقة",
"unit_number": "4",
"paci_number": "12345678"
}
},
"checks": {
"code_lines": "passed",
"expiry": "passed",
"liveness": "passed",
"face_match": { "result": "passed", "score": 0.97 },
"duplicate": "passed",
"same_face": "passed",
"age": "passed",
"device": "passed"
},
"device": {
"os": "iPhone",
"browser": "Safari",
"ip_country": "KWT",
"network": "isp",
"network_name": "Zain Kuwait",
"vpn_suspected": false,
"virtual_camera": false,
"automation": false,
"same_device_24h": 0,
"same_network_24h": 1
},
"risk": {
"score": 0,
"level": "low",
"signals": []
},
"duplicate_of": [],
"same_face_as": [],
"metadata": {},
"document_images": null,
"review": null,
"created_at": "2026-10-08T08:00:00Z",
"completed_at": "2026-10-08T08:01:04Z"
}الحالة تتقدم إلى الأمام فقط:
| الحالة | المعنى |
|---|---|
created | تم إنشاء الرابط، ولم يفتحه المستخدم بعد. |
in_progress | فتح المستخدم الرابط ويقوم بالتصوير. |
in_review | بانتظار مراجعتك، لمدة تصل إلى 24 ساعة. انظر المراجعة اليدوية. |
redo_requested | طلبت من الشخص إعادة خطوة. أنشئ رابط جديد ولم يعد الرابط السابق يعمل. |
approved | نجحت جميع الفحوصات. حالة نهائية. |
declined | فشل فحص أو أكثر، انظر decline_reasons. حالة نهائية. |
expired | لم يكتمل الرابط خلال 24 ساعة. حالة نهائية ولا تحتسب. |
تبقى قيمة document هي null حتى تصبح العملية approved أو declined: تسلم بيانات الوثيقة مع النتيجة النهائية المحتسبة فقط. وأثناء انتظار العملية لمراجعتك، تراها في لوحة التحكم.
أسباب الرفض: document_expired، liveness_failed، face_mismatch، document_mismatch (الوجه الأمامي والخلفي من بطاقتين مختلفتين: يجب أن يظهر في الوجه الأمامي اسم العائلة أو الاسم الأول أو رقم الوثيقة الموجود في السطور المرمزة، وعند تفعيل المراجعة تنتظر العملية بالسبب details_disagree)، under_minimum_age، birth_date_unknown (انظر الحد الأدنى للعمر)، passport_not_allowed (يحتاج التحقق إلى بطاقة هوية وعرض جواز سفر: يتوقف فورا ولا يحتسب)، device_tampering (انظر الجهاز والاتصال)، high_risk (انظر درجة المخاطر). وبعد المراجعة اليدوية: review_face_mismatch، review_document_altered، review_screen_or_print، review_duplicate، review_other وnot_reviewed_in_time. لا ترفض الوثيقة التي تتعذر قراءتها، بل يطلب من الشخص تصويرها مرة أخرى.
حقول الوثيقة المهمة:
| الحقل | المعنى |
|---|---|
number | رقم الوثيقة نفسها. في البطاقة المدنية الكويتية هو الرقم التسلسلي للبطاقة، وليس الرقم المدني. |
personal_number | البطاقة المدنية الكويتية: الرقم المدني المكون من 12 رقما. يعاد فقط إذا صح رقم التحقق فيه وطابق تاريخ الميلاد الذي يحمله ما في البطاقة، وإلا كانت قيمته null. بطاقة الهوية الإماراتية: رقم الهوية المكون من 15 رقما إذا صح رقم التحقق فيه. الجوازات: حقل الرقم الشخصي إن وجد. استخدمه للسماح بحساب واحد لكل شخص. |
name_ar | اسم حامل البطاقة بالعربية، مقروءا من وجه البطاقة المدنية الكويتية. قيمته null إذا لم تتضح قراءته، فاطلبه من الشخص ولا تخمنه. |
name_en | البطاقة المدنية الكويتية: الاسم الكامل بالإنجليزية كما هو مطبوع على وجه البطاقة، بكل الأسماء الوسطى (سطور الرمز لا تحمل إلا الاسم الأول واسم العائلة). يعاد فقط إذا بدأ بالاسم الأول وانتهى باسم العائلة الموجودين في سطور الرمز، وإلا كانت قيمته null. |
address | البطاقة المدنية الكويتية: العنوان المطبوع على ظهر البطاقة، في الحقول area, block, street, avenue, building, floor, unit_type, unit_number وpaci_number (الرقم الآلي للعنوان). الحقل paci_number مأخوذ من سطور الرمز، وهي مدققة. كل جزء آخر يعاد إذا اتضحت قراءته، وما لم تتضح قراءته أو غير مطبوع تكون قيمته null، فاطلبه من الشخص. ولا تكون قيمة address كلها null إلا إذا خالف المطبوع على البطاقة سطور الرمز. الأرقام تعاد نصوصا. رقم الهاتف في البطاقة لا يقرأ أبدا. |
blood_group | البطاقة المدنية الكويتية: فصيلة الدم المطبوعة على ظهر البطاقة، مثل O+. قيمتها null إذا لم تتضح قراءتها. |
surname، given_names | الاسم بالحروف اللاتينية من السطور المرمزة للوثيقة. |
رموز الدول هي الرموز الثلاثية المطبوعة في السطور المرمزة للوثيقة. لا تعيد الواجهة صور الوجه أبدا وتحذف بمجرد صدور النتيجة. وتحذف صور الوثيقة كذلك، إلا إذا كان حسابك يستلم نسخ الوثائق (أدناه). وتحذف البيانات المقروءة من الوثيقة بعد 24 ساعة من صدور النتيجة، فتصبح قيمة document هي null وقيمة document_deleted هي true. احفظ ما تحتاج إليه عند استلام النتيجة.
المراجعة اليدوية
بعض عمليات التحقق ليست صحيحة بوضوح ولا خاطئة بوضوح: الوجه قريب من المطابقة دون أن يبلغ الحد، أو فحص الحضور غير متأكد، أو بيانات البطاقة لم تتضح قراءتها. عند اختيار أرسلها لي للمراجعة (لوحة التحكم، قسم المطورين) تنتظرك هذه العمليات بالحالة in_review بدل رفضها. وعند اختيار ارفضها مباشرة ترفض كما في السابق. تبدأ الحسابات الجديدة والمراجعة مفعلة.
تعرض لك لوحة التحكم سبب الانتظار، والصورة الشخصية بجانب صورة الوثيقة، وأوجه الوثيقة. ثم تختار:
| الإجراء | النتيجة |
|---|---|
| قبول | تصبح الحالة approved. |
| رفض | تصبح الحالة declined مع سبب يبدأ بـ review_. |
| طلب الإعادة | تصبح الحالة redo_requested وينشأ رابط جديد صالح لمدة 24 ساعة. يعيد الشخص الصورة الشخصية فقط، أو بطاقة الهوية والصورة الشخصية. أرسل له الرابط بنفسك: تجده في لوحة التحكم وفي الإشعار بالحقل url. |
العملية التي لا يبت فيها خلال 24 ساعة ترفض بالسبب not_reviewed_in_time. نرسل إليك بريدا إلكترونيا عند وصول عملية للمراجعة، ومرة أخرى عندما تتبقى 6 ساعات. تحفظ الصور فقط أثناء الانتظار، وتحذف بمجرد البت في العملية. تحتسب العملية مرة واحدة عند قبولها أو رفضها.
تحمل عملية التحقق التي أرسلت للمراجعة الحقل review:
"review": { "reasons": ["face_close"], "due_at": "2026-10-11T08:01:04Z", "reviewed": false, "reviewed_at": null, "redo_steps": null, "redo_count": 0 }
الأسباب هي face_close، spoof_unsure، details_unread، possible_photocopy، details_disagree، duplicate_id (انظر البطاقات المكررة)، وsame_face (انظر الوجه نفسه ببطاقات مختلفة)، birth_date_unknown (انظر الحد الأدنى للعمر)، وdevice_tampering وrepeat_device (انظر الجهاز والاتصال)، وhigh_risk (انظر درجة المخاطر). لا يحمل due_at قيمة إلا أثناء الحالة in_review. وقيمة redo_steps هي selfie أو all.
البطاقات المكررة
يتحقق لومكس مما إذا سبق التحقق من البطاقة نفسها في حسابك لمرجع reference مختلف. تتم المطابقة بالرقم المدني أو الرقم الشخصي في الجواز، وإلا فبرقم الوثيقة وبلدها. لا تقارن إلا عمليات حسابك، في الوضع نفسه (فعلي أو تجربة)، والعمليات المقبولة أو التي تنتظر المراجعة فقط. ولا يعد تكرارا أن يتحقق المرجع نفسه مرة أخرى، مثلا ببطاقة مجددة.
- قيمة
checks.duplicateهي"passed"إذا كانت البطاقة جديدة في حسابك، أو"flagged"إذا استخدمت من قبل. - يسرد الحقل
duplicate_ofالعمليات السابقة المطابقة:idوreferenceوstatusوcompleted_at، ويكون فارغا إذا لم توجد. - عند اختيار أرسلها لي للمراجعة تنتظر العملية المكررة بالحالة
in_reviewوبالسببduplicate_id، فتوافق عليها أو ترفضها بالسببreview_duplicate. وعند إيقاف المراجعة يبت في العملية كالمعتاد، ويخبر الحقلduplicate_ofموقعك بالمستخدم الذي يملك هذه البطاقة، ليرفض الحساب الثاني بنفسه.
"duplicate_of": [ { "id": "vrf_3HB71P", "reference": "user_3108", "status": "approved", "completed_at": "2026-09-02T16:05:11Z" } ]
الوجه نفسه ببطاقات مختلفة
يتحقق لومكس مما إذا سبق التحقق من الوجه نفسه في حسابك ببطاقة مختلفة لمرجع reference آخر: شخص واحد يفتح حسابا ثانيا ببطاقة هوية أو جواز سفر آخر. بعد الصورة الشخصية يحفظ لومكس بصمة للوجه لمدة 90 يوما، وهي مجموعة أرقام لا يمكن تحويلها إلى صورة. وتقارن كل عملية جديدة بعملياتك أنت فقط خلال آخر 90 يوما، في الوضع نفسه (فعلي أو تجريبي)، والتي قبلت أو تنتظر المراجعة. ولا تقارن أبدا بعمليات جهات أخرى.
- قيمة
checks.same_faceهي"passed"أو"flagged". ولا يظهر الحقل إذا كان الفحص متوقفا، أو إذا لم يكن في الوثيقة رقم للمقارنة. - يذكر
same_face_asالعمليات السابقة المطابقة:idوreferenceوstatusوcompleted_atوscore، أي مدى تشابه الوجهين من 0 إلى 1 (التنبيه من 0.80). - عند اختيار أرسلها لي للمراجعة تنتظر العملية بالحالة
in_reviewوبالسببsame_face، فتوافق عليها أو ترفضها بالسببreview_duplicate. وإذا كانت المراجعة متوقفة يبت في العملية كالمعتاد، وتضيف المطابقةsame_faceإلى درجة المخاطر. ولا ترفض العملية بسببها وحدها، فقد يتشابه التوائم والأقارب. - استخدام البطاقة نفسها مرة أخرى يكشفه فحص البطاقات المكررة، وليس هذا الفحص.
- الفحص مفعل لكل الحسابات، ويمكنك إيقافه من لوحة التحكم (المطورون، الوجه نفسه ببطاقات مختلفة)، وإيقافه يحذف البصمات المحفوظة. ويجب أن يذكر إشعار الخصوصية في موقعك أن الوجوه تقارن لمنع التسجيل المتكرر.
"checks": { "duplicate": "passed", "same_face": "flagged" }, "same_face_as": [ { "id": "vrf_3HD8Q2", "reference": "user_1874", "status": "approved", "completed_at": "2026-09-02T10:14:00Z", "score": 0.91 } ]
نسخ الوثائق
إذا كانت خدمتك تحتاج نسخة من الهوية لملف المستخدم، فعل نسخ الوثائق من لوحة التحكم في قسم المطورين (0.10 دولار إضافية لكل عملية في الخطتين)، وقبل أول نسخة، يوافق من سجل الدخول إلى حسابك على تحمل جهتك مسؤولية النسخ التي تستلمها، وتسجل الموافقة باسمه وتاريخها ووقتها وعنوان IP، وترسل إلى البريد الإلكتروني لمالك الحساب. ويمكنك إيقاف النسخ في أي وقت. ويبلغ الشخص قبل التصوير بأنك ستستلم نسخة. يصلك كل وجه مستويا ومقصوصا على حواف الوثيقة وفي الاتجاه الصحيح، مهما كانت زاوية التصوير.
عند التفعيل تحمل عملية التحقق المكتملة الحقل document_images:
"document_images": { "sides": ["front", "back"], "expires_at": "2026-10-09T08:01:04Z" }
الأوجه هي front وback لبطاقة الهوية، أو passport للجواز. حمل كل وجه بصيغة JPEG خلال 24 ساعة، وبعدها نحذفها ويعيد الطلب 404 images_unavailable.
curl https://api.lumex.id/v1/verifications/vrf_7KQ2M9/images/front \
-H "Authorization: Bearer lx_live_…" -o front.jpgالإشعارات
أضف عنوان الإشعارات في لوحة التحكم. نرسل طلب POST بمحتوى JSON لكل حدث:
| الحدث | متى |
|---|---|
verification.started | فتح المستخدم الرابط. |
verification.in_review | عملية التحقق بانتظار مراجعتك. |
verification.redo_requested | طلبت من الشخص إعادة خطوة. الحقل data.url هو الرابط الجديد. |
verification.approved | تم قبول التحقق. |
verification.declined | تم رفض التحقق. |
verification.expired | انتهت صلاحية الرابط دون إكمال. |
{
"id": "evt_3HZ81L",
"type": "verification.approved",
"created_at": "2026-10-08T08:01:04Z",
"data": { /* the verification object */ }
}رد بأي حالة 2xx خلال 10 ثوان. إن لم يحدث ذلك نعيد الإرسال على فترات متزايدة لمدة تصل إلى 24 ساعة. قد يصل الحدث نفسه أكثر من مرة، لذا تجاهل أي id سبق أن عالجته.
تحقق من التوقيع في كل إشعار. يحمل كل طلب الترويسة Lumex-Signature بالشكل t=1791446464,v1=5257a8…. احسب HMAC-SHA256 للنص t + "." + المحتوى الخام بالمفتاح السري للإشعارات وقارنه مع v1. ارفض الطلب إذا كان عمر t أكثر من 5 دقائق.
import crypto from "node:crypto"; export function verifyLumex(rawBody, header, secret) { const p = Object.fromEntries(header.split(",").map(x => x.split("="))); const t = Number(p.t); if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false; const expected = crypto.createHmac("sha256", secret) .update(`${t}.${rawBody}`).digest("hex"); if (!p.v1 || p.v1.length !== expected.length) return false; return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(p.v1)); }
function verify_lumex(string $raw, string $header, string $secret): bool { parse_str(str_replace(',', '&', $header), $p); if (empty($p['t']) || abs(time() - (int)$p['t']) > 300) return false; $expected = hash_hmac('sha256', $p['t'] . '.' . $raw, $secret); return hash_equals($expected, $p['v1'] ?? ''); }
استخدم المحتوى الخام كما وصل تماما. تحليل JSON ثم إعادة ترميزه يغير البايتات ويفسد التوقيع.
الأخطاء
تعيد الأخطاء محتوى JSON فيه رمز ثابت code يمكنك فحصه في برنامجك، ورسالة مقروءة message:
{ "error": { "code": "invalid_field", "message": "redirect_url must start with https://" } }| HTTP | متى |
|---|---|
400 | حقل مفقود أو غير صحيح. |
401 | المفتاح مفقود أو خاطئ أو ملغى. |
402 | خطتك غير مفعلة، أو لا يغطي رصيدك المسبق هذه العملية مع العمليات الفعلية التي لم تكتمل بعد. اشحن رصيدك من لوحة التحكم. |
404 | لا توجد عملية تحقق بهذا المعرف في هذا الوضع. |
409 | استخدم المفتاح Idempotency-Key نفسه مع محتوى مختلف، أو ما زال طلب بالمفتاح نفسه قيد التنفيذ (idempotency_in_progress). |
429 | طلبات كثيرة. انتظر عدد الثواني في Retry-After. مع مفتاح التجربة، test_limit: استخدمت العمليات التجريبية المئة خلال 24 ساعة. |
5xx | خطأ من جهتنا. أعد المحاولة بالمفتاح Idempotency-Key نفسه. |
تحتاج مساعدة؟
أخبرنا عن نظامك عبر نموذج التواصل وسنساعدك في ربط موقعك الأول.