الأمان

مفتاحك الخاص يبقى لك

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

• لا تضعه أبدًا في ملف إعدادات، أو متغير بيئة، أو نظام إدارة الشيفرة المصدرية، أو أي مكان يمكن أن يصل إليه سجل (log) أو تقرير أعطال.
• لا يحتاج التوقيع إلا إلى شيء قادر على توقيع البايتات باستخدام ECDSA P-256 وإعادة التوقيع ذي الـ 64 بايت. يمكن لخزنة أو وحدة عتادية توقّع نيابةً عنك أن تقوم بذلك دون أن يدخل المفتاح تطبيقك أبدًا — وتقبل حزم SDK أي أداة توقيع من هذا النوع.

توقّع أنيس الردود المهمة

توقّع أنيس الردّ عندما ينقل مالًا، أو يسلّم البطاقات، أو يُثبت مفتاحك، أو يوقف الوصول. وفي هذه الاستدعاءات كل ردّ موقَّع — النجاح وكل رفض — ويجب أن يشترط عميلك وجود التوقيع ويفحصه قبل أن يتصرف بناءً على الردّ؛ راجع التحقق من الردود. والردّ الذي يصل من أحد هذه الاستدعاءات بلا توقيع، أو بتوقيع لا يصحّ، هو فشل: تخلَّص منه، ولا تتصرف بناءً عليه أبدًا، ولا تكتفِ أبدًا بتسجيله في السجل ثم متابعة العمل. لا تكتب أبدًا «تحقّق من التوقيع إن وُجد» — ففي هذه الاستدعاءات غياب التوقيع هو بالضبط ما يرسله المزوِّر.

أما ردود كل استدعاء آخر فهي غير موقَّعة: ملف تطبيقك، والمحافظ، واستدعاءات الكتالوج الخمسة، وقائمة البطاقات المملوكة، وبطاقة مملوكة واحدة. لا تحمل ترويسة Signature ولا Signature-Input، لكنها تحمل Content-Digest و X-Request-Id كالمعتاد. ولا شيء تتحقق منه فيها — فحماية TLS تكفيها — والرفض الصادر من أحد هذه الاستدعاءات غير موقَّع أيضًا. أما مستند مفاتيح أنيس العامة فغير موقَّع كما كان.

ردود باقات العدادات وقوائم عملياتها ومنتجات الشحن المباشر ومواقعها وعروض أسعارها وقوائم عملياته وقراءة عنوان الإشعارات وقائمة أحداثها غير موقّعة. تظل استدعاءاتها موقّعة. وللإشعارات الواردة ملف تحقق خاص بها، موضح في التحقق من إشعارات Webhook.

استدعاءاتك أنت لا تتغيّر: تظل توقّع كل استدعاء، في كل مسار، تمامًا كما في توقيع الاستدعاءات.

عنوان واحد لكل نسخة نشر

كل نسخة نشر لأنيس منفصلة تمامًا — لها عنوانها ومفاتيحها وبياناتها. لا يوجد إعداد يبدّل بينها؛ فالعنوان الذي تستدعيه هو ما يحدد. والمفتاح المسجَّل لدى نسخة نشر لا يعني شيئًا لأخرى.

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

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

أوقف الوصول بنفسك

استخدم تعليق تطبيقك لإيقاف وصول التطبيق بالكامل، أو إلغاء مفتاح للتطبيق لإيقاف مفتاح واحد، فور الاشتباه باختراق أو الحاجة إلى إيقاف طارئ. يتطلب كلا الاستدعاءين reason من 1 إلى 500 حرف بعد إزالة المسافات الطرفية. وقّع بصمة المحتوى واستخدم رقم استخدام واحد جديدًا؛ لا يلزم أي منهما صلاحية خاصة أو مفتاح منع التكرار للاستدعاء المقبول.

يسري الإيقاف فورًا. ولا يملك صلاحية استئناف التطبيق المعلّق إلا موظفو أنيس. المفتاح الملغى لا يعمل مرة أخرى؛ وإلغاء المفتاح الذي تستخدمه يتطلب دعوة وتسجيلًا جديدين قبل أن تتمكن من التوقيع مجددًا. كل إيقاف، بما فيه الإيقاف الذي يجريه الموظفون، يرسل بريدًا إلى جهة الاتصال الفنية لديك؛ والإيقاف الذي يبدأه فريقك يرسل بريدًا أيضًا إلى support@anis.ly.

إذا فقدت المفتاح الخاص بالكامل فلا تستطيع توقيع استدعاء الإيقاف: تواصل فورًا مع support@anis.ly. أبلغ هناك عن أي اشتباه باختراق دون تأخير، حتى بعد استخدام الإيقاف الذاتي. اقرأ مسودة شروط الأدلة والنزاعات.

الشبكات المسموح بها

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

لتميّز بين السببين، استدعِ GET /v1/profile من الخادم نفسه. إذا رُفض هو أيضًا بالرمز insufficient_scope فالسبب هو الشبكة (أو أن تطبيقك لا يملك الصلاحية profile:read). وإذا نجح فالشبكة سليمة: قارن الصلاحيات التي يذكرها بالصلاحية التي يحتاجها المسار المرفوض.

رموز البطاقات أسرار

تظهر رموز البطاقات في موضعين اثنين فقط: الردّ الذي يُبلغ لأول مرة عن اكتمال طلب شراء، وعملية الكشف. احفظها حيث تحفظ الأسرار، ولا تكتبها أبدًا في السجلات (logs) أو التتبعات (traces) أو تقارير الأخطاء.

الساعة

تحمل التوقيعات وقتها، وكذلك ردود أنيس الموقَّعة. أبقِ ساعة خادمك متزامنة (NTP): الساعة التي تنحرف تؤدي إلى رفض الاستدعاءات بالرمز invalid_credentials وإلى تجاهل الردود الموقَّعة لأنها قديمة جدًا. وقّع لمدة 60 ثانية أو أقل — راجع توقيع الاستدعاءات.

عرض العناوين المسموح بها: بيئة الاختبار فقط — نقاط نهاية للاختبار، غير متاحة في الإنتاج. ردّ القراءة غير موقّع؛ ويجب التحقق من توقيع ردود الإضافة والإزالة، بما فيها الرفض. هذه المسارات الثلاثة مستبعدة دائمًا من حزم SDK.