مرجع API · تسجيل المفتاح

إثبات حيازة المفتاح

POST/v1/enrollments/{invitationId}/proof

يرسل إثبات الحيازة. بعد قبوله ينتظر المفتاح أن يتصل بك موظفو أنيس ويتحققوا من رمز الأمان الخاص به ويؤكّدوه.

الصلاحيةلا شيء

المصادقةرمز التسجيل

ردّ أنيسموقَّع

حدود الموظفين التي يُحتسب ضمنهالا شيء

حزمة SDK لـ ‎.NETenrollment.ProveAsync(submitted, key)

الإثبات الذي لا يُتحقق منه، أو الذي يأتي بعد نحو 30 دقيقة من إرسال المفتاح، لا يُرفض: الرد يقول proofState: "failed". تحقّق من "accepted".
بعد مرور نحو 30 دقيقة على إرسال المفتاح لا يمكن أن ينجح إثبات الحيازة: لا تُعِد الإثبات — اطلب من موظفي أنيس إعادة بدء تسجيل المفتاح. وبعد خمس محاولات إثبات فاشلة تُرفض المحاولة التالية بالرمز invitation_invalid.
الرمز key_duplicate عند إرسال الإثبات يعني أن الإثبات قُبل من قبل (ضاع ردّه فأُرسل الإثبات نفسه مرة أخرى). اقرأ الحالة قبل أي شيء آخر.

المعاملات

الاسم	الموضع	النوع	ملاحظات
`invitationId`إلزامي	`path`	UUID	معرّف UUID بأحرف صغيرة مع الشرطات.

الاستدعاء

مُصرَّح به عبر Authorization: Enrollment <token>؛ غير موقَّع.

الترويسات: Accept-Language (اختياري). تضبطها حزم SDK كلها نيابةً عنك.

المحتوى: EnrollmentProofRequest، بصيغة JSON.

الحقل	النوع	ملاحظات
`keyId`إلزامي	UUID	معرّف المفتاح من خطوة إرسال المفتاح.
`challengeGeneration`إلزامي	integer	رقم التحدّي الذي تجيب عنه.
`signature`إلزامي	string	توقيع ECDSA P-256/SHA-256 على رسالة الإثبات، 64 بايت (ليس DER)، بترميز base64url دون حشو.

الردود

الحالة	المعنى	المحتوى
200	نجاح.	EnrollmentStatus
401	مرفوض: لم تتم المصادقة.	مشكلة
404	مرفوض: غير موجود، أو ليس لك.	مشكلة
409	مرفوض: يتعارض مع الحالة الحالية.	مشكلة
422	مرفوض: الاستدعاء يخالف قاعدة.	مشكلة
429	مرفوض: بلغتَ حدًا.	مشكلة
503	لا قرار: خدمة مطلوبة غير متاحة.	مشكلة

كل ردّ على هذا الاستدعاء موقَّع من أنيس — النجاح وكل رفض. اشترط وجود التوقيع وتحقّق منه قبل أن تتصرف بناءً على الردّ؛ والردّ بلا توقيع فشل، لا يُعدّ ردًّا (كيف).

حالات الرفض

كل رفض لهذا الاستدعاء مشكلةٌ موقَّعة. ابنِ منطقك على رمزها code؛ وكلٌّ منها يرتبط بصفحة تشرح معناه وما عليك فعله.

الخطأ	الرمز	الحالة
الدعوة غير صالحة	`invitation_invalid`	401
غير موجود	`resource_not_found`	404
فشل التحقق	`validation_failed`	422
استُبدل التحدّي	`challenge_expired`	409
الدعوة مستخدمة من قبل	`key_duplicate`	409
تجاوزت حدّ الاستدعاءات	`rate_limited`	429
الخدمة غير متاحة	`dependency_unavailable`	503
انتهت مهلة الاستدعاء	`request_timeout`	504
خطأ داخلي	`internal_error`	500

الأنواع

EnrollmentProofRequest

الحقل	النوع	ملاحظات
`keyId`إلزامي	UUID	معرّف المفتاح من خطوة إرسال المفتاح.
`challengeGeneration`إلزامي	integer	رقم التحدّي الذي تجيب عنه.
`signature`إلزامي	string	توقيع ECDSA P-256/SHA-256 على رسالة الإثبات، 64 بايت (ليس DER)، بترميز base64url دون حشو.

EnrollmentStatus

الحقل	النوع	ملاحظات
`keyId`	UUID	معرّف مفتاحك.
`challengeGeneration`	integer	رقم التحدّي الحالي.
`proofState`	string	`pending` أو `accepted` أو `failed` — إثبات لم يُتحقق منه أو جاء متأخرًا. وبعد خمس محاولات إثبات فاشلة تُرفض المحاولة التالية بالرمز `invitation_invalid`: اطلب من موظفي أنيس إعادة بدء تسجيل المفتاح.
`approvalState`	string	`pending` ما دام موظفو أنيس لم يؤكّدوا المفتاح، و `approved` بعد أن يصبح فعّالًا، و `notApplicable` في غير ذلك.
`state`	string	`pendingInvitation` أو `pendingProof` أو `pendingApproval` أو `active` — المفتاح يوقّع الاستدعاءات — أو `unavailable` (المفتاح قيد الاستبدال بمفتاح أحدث). أما المفتاح الملغى أو المُنهى أو المنتهي الصلاحية فلا يُعرض: تُجيب قراءة الحالة بالرمز `resource_not_found`.
`expiresAt`	string (date-time)	وقت انتهاء خطوة التسجيل الحالية: الدعوة، ما دامت مفتوحة. لا يظهر بعد أن يصبح المفتاح فعّالًا أو حين لا يعود متاحًا — أما تاريخ انتهاء المفتاح نفسه فهو `keyExpiresAt`.
`keyExpiresAt`	string (date-time)	تاريخ توقف مفتاحك النشط عن العمل (لا يظهر قبل أن يصبح المفتاح نشطًا). اطلب من موظفي أنيس مفتاحًا بديلًا قبله بأسابيع: فالمفتاح الذي تجاوز تاريخ انتهائه يُرفض بالرمز `invalid_credentials` في كل استدعاء، بما في ذلك كشف بطاقات اشتريتها من قبل.