تسجيل مفتاح

لا يمكنك استدعاء الواجهة البرمجية حتى يصبح أحد مفاتيحك نشطًا. تسجيل المفتاح هو ما يحوّل دعوة من أنيس إلى ذلك المفتاح.

الخطوات

1. ترسل إليك أنيس دعوة بالبريد الإلكتروني — من العنوان no-reply@anis.ly، إلى جهة الاتصال الفنية التي أعطيتها. تحمل معرّف المفتاح (وهو معرّف الدعوة الذي تستخدمه الاستدعاءات أدناه) والدعوة (رمز التسجيل الصالح للاستخدام مرة واحدة) والعنوان الذي تستدعيه — قيمة authority في حزمة SDK — وهي صالحة لمدة 24 ساعة. دعوة بيئة الاختبار تحمل [Sandbox · تجريبي] في عنوانها، ومفتاحها لا يعمل أبدًا في الإنتاج.
2. تُنشئ زوج مفاتيح P-256. احفظ النصف الخاص أولًا، في المكان الذي تحفظ فيه الأسرار.
3. ترسل النصف العام وتتلقّى تحدّيًا.
4. تُثبت أنك تحوز النصف الخاص بتوقيع رسالة مبنية من ذلك التحدّي.
5. تقرأ لموظفي أنيس رمز الأمان — عبر الهاتف. يعرضه برنامجك بعد إرسال المفتاح، وتُرجعه الواجهة البرمجية في الحقل safetyCode. يتصل موظفو أنيس بجهة الاتصال الفنية، ويطلبون الرمز، ويقارنونه بالمفتاح الذي أرسلته. وبعد أن يؤكّدوا المفتاح يصبح فعّالًا ويوقّع الاستدعاءات، ثم يصلك بريد إلكتروني بعنوان «مفتاحك أصبح فعّالًا».

رمز الأمان من 16 خانة، يُكتب XXXX-XXXX-XXXX-XXXX: صيغة قصيرة لبصمة المفتاح. لا تهم الشرطات أو المسافات أو حالة الأحرف عند قراءته. فالمكالمة هي التي تتحقق من أن المفتاح الذي لدى أنيس هو المفتاح الذي أنشأته أنت.

تُفوَّض استدعاءات تسجيل المفتاح الأربعة بالرمز — Authorization: Enrollment <token> — لا بتوقيع. ومع ذلك تبقى ردودها موقّعة من أنيس — كل ردّ، نجاحًا كان أم رفضًا — ويشترط برنامجك وجود التوقيع ويتحقق منه كما في أي استدعاء موقَّع (راجع التحقق من الردود)؛ والردّ على تسجيل المفتاح بلا توقيع فشل. ويذكر الإثبات أيضًا معرّف مفتاحك: ورمز التسجيل الذي لا يخصّ ذلك المفتاح يُجاب كما يُجاب المفتاح غير المعروف، بالرمز resource_not_found.

باستخدام حزمة SDK لـ ‎.NET

using var key = ECDsa.Create(ECCurve.NamedCurves.nistP256);
await File.WriteAllTextAsync("/secure/partner-key.pem", key.ExportPkcs8PrivateKeyPem(), ct);   // first

using var enrollment = AnisEnrollmentClient.Create(authority, invitationId, enrollmentToken);

var submitted = await enrollment.SubmitKeyAsync(new EnrollmentKeyRequest
{
    PublicJwk = AnisEnrollmentClient.PublicJwkOf(key),
    NotBefore = DateTimeOffset.UtcNow,
    ExpiresAt = DateTimeOffset.UtcNow.AddYears(1),
}, ct);

var status = await enrollment.ProveAsync(submitted, key, ct);
if (status.ProofState != "accepted")
    throw new InvalidOperationException("The proof failed — check the key and prove again.");   // state: pendingApproval

Console.WriteLine($"key id {submitted.KeyId}");
Console.WriteLine($"Your safety code: {submitted.SafetyCode} — Anis staff will call you and ask you to read it.");

submitted.KeyId هو معرّف المفتاح الذي سيحمله كل توقيع. وsubmitted.SafetyCode هو الرمز الذي تقرؤه لموظفي أنيس عبر الهاتف. SafetyCode والفحص الوارد أدناه موجودان في حزمة SDK منذ الإصدار 1.3.0.

وعند إرسال المفتاح تفحص حزمة SDK لـ ‎.NET أيضًا البصمة التي يُرجعها الخادم مقابل مفتاحك أنت. وإذا اختلفتا فإنها تتوقف بالاستثناء EnrollmentKeyMismatchException ولا ترسل شيئًا بعد ذلك: لا تتابع، واكتب إلى support@anis.ly.

بدون حزمة SDK

أرسل المفتاح — POST /v1/enrollments/{invitationId}/keys:

{
  "publicJwk": { "kty": "EC", "crv": "P-256", "x": "<32 bytes, base64url>", "y": "<32 bytes, base64url>" },
  "notBefore": "2026-09-24T08:00:00Z",
  "expiresAt": "2027-09-24T08:00:00Z"
}

أرسل الحقول العامة فقط — يُرفض المفتاح إذا احتوى على d. لا يُستخدم من النافذة الزمنية إلا طولها، وتبدأ عندما يفعّل موظفو أنيس المفتاح. تعتمد أنيس الأقصر بين مدة الصلاحية التي تطلبها والمدة التي حدّدها موظفو أنيس (ولا تزيد أبدًا على سنتين). يحمل الردّ keyId وthumbprint وsafetyCode وchallenge وchallengeGeneration. احتفظ بالتحدّي إلى أن يُقبل الإثبات: فهو لا يُعاد إلا هنا. واعرض safetyCode على من سيستقبل مكالمة موظفي أنيس — فهو الرمز الذي سيقرؤه.

لا يحتوي إرسال المفتاح على حقل لشبكاتك. أبلغ موظفي أنيس بالشبكات التي ستستدعي منها عندما تطلب الوصول (انظر الحصول على الوصول). أي استدعاء من عنوان آخر يُرفض بالرمز insufficient_scope.

ابنِ رسالة الإثبات. ليست التحدّي وحده — بل خمس قيم، يفصل بين كل قيمتين محرف \n واحد، ولا يأتي بعد القيمة الأخيرة أي محرف:

anis.partners.v2.credential-proof
<keyId, lower-case with hyphens>
<challengeGeneration, as a decimal number>
<SHA-256 of the challenge's UTF-8 bytes, as lower-case hex>
<thumbprint, exactly as returned>

وقّع تلك البايتات باستخدام ECDSA P-256 وSHA-256. يجب أن يكون التوقيع بالصيغة ذات 64 بايت (r ثم s، كلٌّ منهما 32 بايت)، لا بصيغة DER، ومرمّزًا بـ base64url دون حشو (padding).

أرسل الإثبات — POST /v1/enrollments/{invitationId}/proof:

{ "keyId": "<keyId>", "challengeGeneration": 1, "signature": "<86 base64url characters>" }

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

حالة المفتاح

اقرأ حالة تسجيل المفتاح باستخدام الرمز نفسه:

قد تظهر الحالة active قبل أن تعمل الاستدعاءات الموقّعة بالمفتاح بلحظة: إذا رُفض أول استدعاء لك، فانتظر لحظة ثم أعِد الاستدعاء نفسه.

keyExpiresAt هو تاريخ توقف مفتاحك النشط عن العمل (لا يظهر قبل أن يصبح المفتاح نشطًا). اطلب من موظفي أنيس مفتاحًا بديلًا قبله بأسابيع: فالمفتاح الذي تجاوز تاريخ انتهائه يُرفض بالرمز invalid_credentials في كل استدعاء، بما في ذلك كشف بطاقات اشتريتها من قبل.

المهل الزمنية

• الدعوة صالحة لمدة 24 ساعة. اقرأ الدعوة لمعرفة قيمة expiresAt الدقيقة. وهي لا تحدّ إلا إرسال المفتاح: بعد إرسال مفتاحك تظل قراءة الحالة تُجيب برمز التسجيل نفسه حتى بعد انتهاء صلاحية الدعوة، إلى أن ينتهي المفتاح.
• الإثبات يجب أن يلي إرسال المفتاح خلال 30 دقيقة تقريبًا افتراضيًا؛ والإثبات المتأخر يعود بالنتيجة "failed" ولا يمكن أن ينجح بعد ذلك — لا تُعِد الإثبات، واطلب من موظفي أنيس إعادة بدء تسجيل المفتاح. إذا كان مفتاحك محفوظًا في خزنة مفاتيح أو وحدة عتادية يتطلّب التوقيع فيها موافقة، فرتّب تلك الموافقة قبل أن ترسل المفتاح.

عندما يحدث خطأ

يستطيع موظفو أنيس إعادة بدء تسجيل المفتاح الواحد عددًا محدودًا من المرات — أربع مرات افتراضيًا، أي خمس دعوات في المجموع. احفظ المفتاح الخاص قبل أن ترسل النصف العام، كي لا تُستهلك إعادة بدء على مفتاح مفقود.

استبدال المفاتيح وإلغاؤها

• استبدال مفتاح. يبدأ موظفو أنيس الاستبدال وتُرسل دعوة جديدة بالبريد الإلكتروني إلى جهة الاتصال الفنية. سجّل المفتاح الجديد تمامًا كما سبق. بمجرد تأكيده، يعمل المفتاحان كلاهما خلال فترة تداخل يحددها موظفو أنيس — تصل إلى 30 يومًا، تُحسب من وقت بدء عمل المفتاح الجديد. عند انتهاء فترة التداخل يُرفض المفتاح القديم تلقائيًا بالرمز invalid_credentials — دون أن يحتاج أحد إلى فعل شيء. انقل أداة التوقيع لديك إلى معرّف المفتاح الجديد قبل ذلك. واطلب مفتاحًا بديلًا قبل keyExpiresAt لمفتاحك بأسابيع.
• إلغاء مفتاح. منذ اللحظة التي يلغي فيها موظفو أنيس مفتاحًا، يُرفض كل استدعاء موقّع به بالرمز invalid_credentials. إلغاء مفتاح لم تعد تستخدمه لا يؤثر في مفتاحك الحالي.