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

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

التقاط جديد — يُرسل صور المستند بصيغة 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

الدولة	الرمز	الوصف
AR	6	جواز سفر أرجنتيني
AR	7	DNI الأرجنتيني
AR	49	رخصة القيادة الأرجنتينية (Licencia Nacional de Conducir)
AT	34	الرقم الضريبي النمساوي (STNR)
BE	36	الرقم الوطني البلجيكي (NN)
BR	1	CPF البرازيلي
BR	5	جواز سفر برازيلي
BR	14	CNPJ البرازيلي
CA	28	SIN الكندي
CH	33	رقم AHV/AVS السويسري
CL	9	RUN التشيلي
CL	52	جواز سفر تشيلي
CL	57	رخصة القيادة التشيلية (Licencia de Conducir)
CO	26	NIT الكولومبي
CO	53	جواز سفر كولومبي
CO	55	رخصة القيادة الكولومبية (Licencia de Conducción)
CO	56	بطاقة المواطنة الكولومبية (Cédula de Ciudadanía)
DE	41	رقم التعريف الضريبي الألماني (IdNr)
DK	29	CPR الدنماركي
EC	10	NI الإكوادوري
ES	50	رقم هوية الأجانب الإسباني (NIE)
ES	51	وثيقة الهوية الوطنية الإسبانية (DNI)
FI	35	رمز الهوية الشخصية الفنلندي (HETU)
FR	46	الرقم الضريبي المرجعي الفرنسي (SPI)
GB	30	رقم التأمين الوطني البريطاني (NINO)
GT	12	CUI الغواتيمالي
ID	16	NIK الإندونيسي
IE	47	رقم الخدمة العامة الشخصي الأيرلندي (PPSN)
IT	37	Codice Fiscale الإيطالي (CF)
LU	48	رقم الهوية الوطني اللوكسمبورغي (Matricule)
MX	2	CURP المكسيكي
MX	25	RFC المكسيكي (شخص طبيعي)
MX	58	رخصة القيادة المكسيكية (Licencia de Conducir)
NG	8	NIN النيجيري
NG	20	رقم التحقق المصرفي النيجيري (BVN)
NG	43	رمز BVN النيجيري (مُجزّأ)
NG	44	رمز NIN النيجيري (مُجزّأ)
NL	42	رقم خدمة المواطن الهولندي (BSN)
NO	39	رقم الهوية الوطني النرويجي (Fødselsnummer)
PE	27	RUC البيروفي
PE	40	DNI البيروفي
PE	54	جواز سفر بيروفي
PL	31	PESEL البولندي
PT	45	رقم التعريف الضريبي البرتغالي (NIF)
SE	32	الرقم الشخصي السويدي (PNR)
SE	38	الرقم التنسيقي السويدي (Samordningsnummer)
TR	24	رقم الهوية التركي (TCKN)
US	4	SSN الأمريكي
US	11	جواز سفر أمريكي
US	18	رخصة قيادة أمريكية
US	21	بطاقة جواز سفر أمريكية
US	22	جواز سفر أمريكي مصنوع من البولي كاربونات
US	23	بطاقة هوية أمريكية
UY	13	CI الأوروغوياني
ZZ	15	عنوان البريد الإلكتروني
ZZ	17	رقم الهاتف
—	0	غير محدد
—	3	معرّف Unico الداخلي

مثال

التقاط جديد — cURL
التقاط جديد — Node.js
إعادة الاستخدام — cURL
إعادة الاستخدام — Node.js

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..." }
      ]
    }
  }'

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 -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"
    }
  }'

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	نوع المستند المُعرَّف، كاسم قاموس مؤهَّل بالكامل. انظر قيم `document.type` أدناه.
`document.cpfMatch`	boolean	`true` إذا تطابق المعرّف المستخرج من المستند مع `subject.code`.
`document.faceMatch`	boolean	`true` إذا تطابق وجه المستند مع السيلفي البيومتري من `document.authProcessId`.
`document.content`	object	الحقول المستخرجة عبر OCR. يختلف الهيكل باختلاف نوع المستند — انقر هنا لتفاصيل الحقول.
`document.fileUrls`	array	روابط مؤقتة (صالحة لمدة 10 دقائق) لتنزيل صور المستند.

لا تظهر في document.content إلا الحقول المستخرجة بنجاح؛ وأي حقل لم يتمكن OCR من قراءته يُحذف بدلاً من إعادته فارغاً.

قيم document.type

المخطط الموحّد

جميع أنواع المستندات التي تستخدم المخطط الموحّد — unified_schema في مرجع الحقول — تُعاد في document.type بالشكل unico.moja.dictionary.<country>.generic.v1.<DocumentType>، حيث <country> هو رمز ISO 3166-1 alpha-2 بأحرف صغيرة و<DocumentType> هو النوع المُعرَّف. على سبيل المثال:

unico.moja.dictionary.ar.generic.v1.IdCard: بطاقة الهوية الأرجنتينية
unico.moja.dictionary.us.generic.v1.PolycarbonatePassport: جواز سفر أمريكي من البولي كربونات

المخططات الخاصة

أنواع المستندات التي تستخدم مخطط حقول خاصًا بها — المدرجة ضمن specific_document_schemas في مرجع الحقول — مبيّنة في الجدول أدناه:

الدولة	القيمة	المستند
BR	`unico.moja.dictionary.br.rg.v2.Rg`	RG
BR	`unico.moja.dictionary.br.cnh.v2.Cnh`	CNH (رخصة القيادة)
BR	`unico.moja.dictionary.br.cin.v1.Cin`	CIN
BR	`unico.moja.dictionary.br.passaporte.v1.Passaporte`	جواز السفر
MX	`unico.moja.dictionary.mx.ine.v1.Ine`	بطاقة الناخب INE
MX	`unico.moja.dictionary.mx.lpc.v1.Lpc`	Licencia para conducir (رخصة القيادة)
MX	`unico.moja.dictionary.mx.pasaporte.v1.Pasaporte`	جواز السفر
—	`unico.moja.dictionary.other.unknown.v1.Unknown`	تعذّر تحديد النوع — `document.content` فارغ

لا يتم إجراء أي استخراج OCR ولا يتم الإبلاغ عن أي حقل عندما يكون document.type هو unico.moja.dictionary.other.unknown.v1.Unknown.

رموز الخطأ

400 Bad Request
403 Forbidden
409 Conflict
500 Internal Server Error

الرمز	الرسالة	الوصف
`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.

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

الرمز	الرسالة	الوصف
`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 غير صالح أو غير موجود.

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

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

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

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

نقطة النهاية​

الطلب​

مثال​

الاستجابات​

رموز الخطأ​

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