إنشاء عملية مستند

تتعامل هذه النقطة النهائية مع تدفقَين للمستند يشتركان في نفس المسار لكنهما يختلفان في معاملات الجسم:

• التقاط جديد — يُرسل صور المستند بصيغة base64 للمعالجة (يُشترط وجود document.files).
• إعادة الاستخدام — يتخطى الالتقاط بالإشارة إلى مستند ملتقط مسبقاً (يُشترط وجود document.documentId).

يتحدد التدفق النشط بناءً على ما إذا كان document.documentId موجوداً في جسم الطلب.

قبل إنشاء عملية مستند، استخدم الحصول على المستندات القابلة لإعادة الاستخدام للتحقق مما إذا كان المستخدم لديه بالفعل مستند متاح لإعادة الاستخدام.

للاطلاع على تدفق التكامل الكامل، راجع نظرة عامة على API.

نقطة النهاية

البيئة	الرابط
الإنتاج	POST https://api.id.unico.app/processes/v1
بيئة الاختبار	POST https://api.id.uat.unico.app/processes/v1

الطلب

الترويسات

الترويسة	القيمة
Authorization	Bearer <access_token> (انظر المصادقة)
APIKEY	مفتاح API المُزوَّد مع تفعيل ميزتي التقاط المستند وإعادة استخدامه.
Content-Type	application/json

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

التقاط جديد

الحقل	النوع	مطلوب	الوصف
subject.duiType	integer	نعم	معرّف نوع الوثيقة. انظر قيم duiType أدناه.
subject.code	string	نعم	قيمة معرّف المستخدم كما هو محدد في subject.duiType. بدون نقاط أو شرطات.
subject.name	string	لا	الاسم الكامل.
subject.gender	string	لا	M أو F.
subject.birthDate	string (ISO 8601)	لا	تاريخ الميلاد (YYYY-MM-DD).
subject.email	string	لا	عنوان البريد الإلكتروني.
subject.phone	string	لا	رقم هاتف بتنسيق E.164.
document.purpose	string	نعم	الغرض التجاري. القيم: creditprocess، carpurchase، paybypaycheck، onboarding، fgts.
document.authProcessId	string	نعم	معرّف العملية البيومترية المرتبطة بالتقاط هذا المستند.
document.files	array	نعم	صور المستند بصيغة base64 (وجه أمامي و/أو خلفي).
document.files[].data	string	نعم	صورة المستند بصيغة base64 (PNG أو JPEG أو WebP، بحد أقصى 800 كيلوبايت).
subsidiaryId	string	لا	معرّف الفرع — مطلوب فقط إذا كانت هناك فروع متعددة.

إعادة الاستخدام

الحقل	النوع	مطلوب	الوصف
subject.duiType	integer	نعم	معرّف نوع الوثيقة. انظر قيم duiType أدناه.
subject.code	string	نعم	قيمة معرّف المستخدم كما هو محدد في subject.duiType. بدون نقاط أو شرطات.
subject.name	string	لا	الاسم الكامل.
subject.gender	string	لا	M أو F.
subject.birthDate	string (ISO 8601)	لا	تاريخ الميلاد (YYYY-MM-DD).
subject.email	string	لا	عنوان البريد الإلكتروني.
subject.phone	string	لا	رقم هاتف بتنسيق E.164.
document.purpose	string	نعم	الغرض التجاري. القيم: creditprocess، carpurchase، paybypaycheck، onboarding، fgts.
document.authProcessId	string	نعم	معرّف العملية البيومترية المرتبطة بهذا المستند.
document.documentId	string	نعم	معرّف مستند ملتقط مسبقاً (يُحصل عليه من الحصول على المستندات القابلة لإعادة الاستخدام). عند توفره يمكن حذف document.files.
subsidiaryId	string	لا	معرّف الفرع — مطلوب فقط إذا كانت هناك فروع متعددة.

قيم duiType

الدولة	الرمز	الوصف
BR	1	CPF البرازيلي
BR	5	جواز سفر برازيلي
MX	2	CURP المكسيكي
AR	6	جواز سفر أرجنتيني
AR	7	DNI الأرجنتيني
US	4	SSN الأمريكي
US	11	جواز سفر أمريكي
US	18	رخصة قيادة أمريكية
ID	16	NIK الإندونيسي
NG	8	NIN النيجيري
CL	9	RUN التشيلي
EC	10	NI الإكوادوري
GT	12	CUI الغواتيمالي
UY	13	CI الأوروغوياني
ZZ	15	عنوان البريد الإلكتروني
ZZ	17	رقم الهاتف
MX	25	RFC المكسيكي (شخص طبيعي)
CO	26	NIT الكولومبي
PE	27	RUC البيروفي
CA	28	SIN الكندي
DK	29	CPR الدنماركي
GB	30	رقم التأمين الوطني البريطاني (NINO)
PL	31	PESEL البولندي
SE	32	الرقم الشخصي السويدي (PNR)
AT	34	الرقم الضريبي النمساوي (STNR)
FI	35	رمز الهوية الشخصية الفنلندي (HETU)
—	0	غير محدد
—	3	معرّف Unico الداخلي

مثال

التقاط جديد — cURL

curl -X POST https://api.id.unico.app/processes/v1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": {
      "duiType": 1,
      "code": "12345678909",
      "name": "Luke Skywalker"
    },
    "document": {
      "purpose": "onboarding",
      "authProcessId": "80371b2a-3ac7-432e-866d-57fe37896ac6",
      "files": [
        { "data": "/9j/4AAQSkZJR..." }
      ]
    }
  }'

التقاط جديد — Node.js

import fetch from 'node-fetch';

const res = await fetch('https://api.id.unico.app/processes/v1', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.UNICO_ACCESS_TOKEN}`,
    'APIKEY': process.env.UNICO_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    subject: {
      duiType: 1,
      code: '12345678909',
      name: 'Luke Skywalker'
    },
    document: {
      purpose: 'onboarding',
      authProcessId: '80371b2a-3ac7-432e-866d-57fe37896ac6',
      files: [{ data: documentImageBase64 }]
    }
  })
});

const result = await res.json();

إعادة الاستخدام — cURL

curl -X POST https://api.id.unico.app/processes/v1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": {
      "duiType": 1,
      "code": "12345678909"
    },
    "document": {
      "purpose": "onboarding",
      "authProcessId": "80371b2a-3ac7-432e-866d-57fe37896ac6",
      "documentId": "doc-abc-123"
    }
  }'

إعادة الاستخدام — Node.js

import fetch from 'node-fetch';

const res = await fetch('https://api.id.unico.app/processes/v1', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.UNICO_ACCESS_TOKEN}`,
    'APIKEY': process.env.UNICO_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    subject: {
      duiType: 1,
      code: '12345678909'
    },
    document: {
      purpose: 'onboarding',
      authProcessId: '80371b2a-3ac7-432e-866d-57fe37896ac6',
      documentId: 'doc-abc-123'
    }
  })
});

const result = await res.json();

الاستجابات

200 OK

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "document": {
    "id": "doc-abc-123",
    "type": "unico.moja.dictionary.br.cnh.v2.Cnh",
    "cpfMatch": true,
    "faceMatch": true,
    "content": {
      "numero": "12345678",
      "nomeCivil": "Luke Skywalker",
      "dataNascimento": "2000-05-20T00:00:00Z",
      "categoria": "B",
      "dataExpiracao": "2030-05-20T00:00:00Z"
    },
    "fileUrls": [
      "https://storage.unico.app/documents/doc-abc-123/front.jpg"
    ]
  }
}

الحقل	النوع	الوصف
id	string (UUID)	معرّف العملية.
status	integer	3 (اكتمل بنجاح)، 5 (اكتمل بفشل).
document.id	string	معرّف المستند الملتقط. استخدم هذه القيمة في طلبات document.documentId المستقبلية لإعادة الاستخدام.
document.type	string	نوع المستند المُعرَّف. القيم المحتملة: unico.moja.dictionary.br.rg.v2.Rg، unico.moja.dictionary.br.cnh.v2.Cnh، unico.moja.dictionary.br.cin.v1.Cin، unico.moja.dictionary.br.passaporte.v1.Passaporte.
document.cpfMatch	boolean	true إذا تطابق المعرّف المستخرج من المستند مع subject.code.
document.faceMatch	boolean	true إذا تطابق وجه المستند مع السيلفي البيومتري من document.authProcessId.
document.content	object	الحقول المستخرجة عبر OCR. يختلف الهيكل باختلاف نوع المستند.
document.fileUrls	array	روابط مؤقتة (صالحة لمدة 10 دقائق) لتنزيل صور المستند.

400 Bad Request

الحمولة مشوهة أو الصورة غير صالحة أو الحقول المطلوبة مفقودة. انظر رموز الخطأ أدناه.

403 Forbidden

رمز Bearer أو APIKEY مفقود أو منتهي الصلاحية أو غير صالح. انظر المصادقة.

409 Conflict

processId المُقدَّم موجود مسبقاً لهذا المستأجر. انظر رموز الخطأ أدناه.

رموز الخطأ

400 Bad Request

الرمز	الرسالة	الوصف
99989	The document is invalid.	كائن document يحتوي على هيكل غير صالح.
99988	The document is empty.	كائن document مفقود من جسم الطلب.
20900	O base64 informado não é válido.	معامل base64 غير صالح. الأسباب المحتملة: ليست صورة أو محاولة حقن.
20807	A imagem precisa estar no padrão HD ou possuir uma resolução superior a 640 x 480.	دقة الصورة المرفوعة منخفضة جداً.
20509	The subject.name field is invalid.	subject.name يحتوي على أحرف غير صالحة.
20508	The subject.gender field is invalid.	يجب أن يكون subject.gender إما M أو F.
20507	O parâmetro subject.code é inválido.	قيمة المعرّف غير قياسية أو غير موجودة.
20506	O base64 informado é muito grande. O tamanho máximo suportado é até 800kb.	حجم الصورة يتجاوز 800 كيلوبايت؛ اضغط بصيغة JPEG92.
20505	O base64 informado não é suportado. Os formatos aceitos são png, jpeg e webp.	تنسيق base64 غير صالح أو غير مدعوم.
20068	The document.documentId or document.files parameter must be present.	لم يتم توفير document.documentId ولا document.files.
20067	The document.purpose parameter is invalid.	قيمة غير معروفة في document.purpose.
20066	The document.authProcessId parameter is invalid.	قيمة غير صالحة في document.authProcessId.
20062	The useCase field is invalid.	قيمة غير معروفة في حقل useCase.
20021	The subject.phone field is invalid.	تنسيق subject.phone غير صالح (رمز الاتصال الدولي + رمز المنطقة + الرقم، 13 رقماً).
20019	The subject.birthDate field is invalid.	subject.birthDate خارج تنسيق ISO 8601 (YYYY-MM-DD).
20009	O parâmetro imagebase64 não foi informado.	معامل صورة المستند مفقود.
20008	The subject.email field is invalid.	تنسيق البريد الإلكتروني غير صالح في subject.email.
20005	O parâmetro subject.code não foi informado.	معامل subject.code مفقود.
20004	O parâmetro subject não foi informado.	معامل subject مفقود.
20003	The request body is missing or invalid.	حمولة فارغة أو غير صالحة.
20002	O parâmetro APIKey não foi informado.	معامل APIKEY مفقود من ترويسة الطلب.
20001	O parâmetro authtoken não foi informado.	معامل رمز التكامل مفقود من ترويسة الطلب.
10508	The JWT with the captured face has already been used.	لا يمكن استخدام JWT إلا مرة واحدة.
10507	The JWT with the captured face is expired.	JWT منتهي الصلاحية؛ يجب إرساله خلال 10 دقائق.
10506	The imageBase64 field is not a valid JWT from SDK.	imageBase64 ليس JWT صالحاً صادراً عن SDK.

403 Forbidden

الرمز	الرسالة	الوصف
30017	User does not have permission to perform this action.	JWT مشوه أو مستخدم لا يملك صلاحية تنفيذ هذه العملية.
10502	O token informado está expirado.	رمز الوصول منتهي الصلاحية.
10501	O token informado é inválido.	رمز المصادقة غير صالح.
10201	O AppKey informado é inválido.	APIKEY غير صالح أو غير موجود.

409 Conflict

الرمز	الرسالة	الوصف
20073	The processID already exists.	processId المُقدَّم موجود مسبقاً لهذا المستأجر.

500 Internal Server Error

الرمز	الرسالة	الوصف
99999	Internal failure! Try again later	عند حدوث خطأ داخلي.

الخطوات التالية

• للتحقق مما إذا كان المستند متاحاً قبل هذا الاستدعاء، انظر الحصول على المستندات القابلة لإعادة الاستخدام.
• لإنشاء عملية بيومترية (مطلوبة لـ document.authProcessId)، انظر إنشاء عملية.