لومكس English ابدأ الآن

للمطورين

مرجع الواجهة البرمجية

الإصدار 1 · العنوان الأساسي https://api.lumex.id/v1

البداية السريعة

  1. أنشئ عملية تحقق من خادمك لأحد مستخدميك.
  2. أرسل المستخدم إلى الرابط url في الرد. يصور بطاقة هويته أو جواز سفره ويلتقط صورة شخصية قصيرة من متصفح هاتفه.
  3. نرسل النتيجة إلى عنوان الإشعارات لديك، ونعيد المستخدم إلى redirect_url.

جميع الطلبات والردود بصيغة JSON. استدع الواجهة من خادمك فقط، وليس من المتصفح أو تطبيق الجوال، لأن مفتاحك السري يجب أن يبقى سريا.

المصادقة

أرسل مفتاحك السري في الترويسة Authorization. تحصل على مفتاحين في لوحة التحكم:

المفتاحالاستخدام
lx_test_…وضع التجربة. يشغل الخطوات كاملة مع شريط يوضح أنها تجربة. بلا رسوم. حتى 100 عملية تجريبية خلال 24 ساعة.
lx_live_…الوضع الفعلي. تحقق حقيقي، يخصم من العمليات المشمولة أو من رصيدك المسبق.
Authorization: Bearer lx_live_…

إنشاء عملية تحقق

POST/v1/verifications
الحقلالنوعالوصف
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_tamperingin_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_tampering60
الوجه نفسه لمستخدم آخر ببطاقة مختلفةsame_face40
قد تكون صورة لشاشة أو ورقة مطبوعةspoof_suspected35
تطابق الوجه أقل من الحد لكنه قريب منهface_close30
البطاقة نفسها مستخدمة لمستخدم آخرduplicate_id30
بيانات البطاقة غير متطابقةdetails_disagree30
الهاتف نفسه لثلاثة مستخدمين آخرين أو أكثر خلال 24 ساعةrepeat_device30
قد تكون البطاقة نسخة مصورةpossible_photocopy25
الاتصال نفسه لثلاثة مستخدمين آخرين أو أكثر خلال 24 ساعةrepeat_network15
الهاتف نفسه لمستخدم أو مستخدمين آخرين خلال 24 ساعةshared_device10
شبكة VPN أو مركز بياناتvpn10
تعذرت قراءة بعض البياناتdetails_unread10
توقيت الهاتف يختلف عن توقيت الاتصالtimezone_mismatch5

تجمع النقاط بحد أقصى 100. المستويات: low أقل من 30، وmedium من 30 إلى 59، وhigh من 60. وتبقى شبكة VPN وحدها (10) أو اتصال مكتب مشترك (15) ضمن المستوى المنخفض.

يحدد إعداد الفحوصات عالية المخاطر (لوحة التحكم، المطورون) ما يحدث لعملية تبلغ درجتها 60 أو أكثر وكانت ستقبل:

  • عرض الدرجة فقط (الافتراضي): لا يتغير شيء.
  • إرسالها للمراجعة: تنتقل العملية إلى in_review بالسبب high_risk. ويتطلب ذلك ضبط عمليات التحقق غير الواضحة على المراجعة.
  • رفضها: ترفض العملية بالسبب high_risk. ويطلب من الشخص التواصل مع موقعك، ولا يرى الدرجة أبدا.

يحمل الحقل risk القيم score وlevel وsignals (الرموز أعلاه، الأقوى أولا). وقيمته null حتى تنتهي خطوة الصورة الشخصية، وللعمليات التي توقفت قبلها (مثل التحقق من العمر)، وللعمليات التي سبقت درجة المخاطر.

جلب عملية تحقق

GET/v1/verifications/{id}

يعيد كائن التحقق كاملا. استخدمه للتأكد من إشعار وصلك، أو للاستعلام الدوري إذا لم تتمكن من استقبال الإشعارات.

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.

GET/v1/verifications/{id}/images/{side}
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));
}

استخدم المحتوى الخام كما وصل تماما. تحليل 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 نفسه.

تحتاج مساعدة؟

أخبرنا عن نظامك عبر نموذج التواصل وسنساعدك في ربط موقعك الأول.