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

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

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

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

الطلب​

مثال​

الاستجابات​

رموز الخطأ​

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